The Tenable Exposure Management tags API enables users to search for their organization's tags. Additionally, API endpoints are provided to retrieve a list of asset and tag properties that can be used as filters on endpoints that support them. For more information, see [Tagging](https://docs.tenable.com/exposure-management/Content/exposure-management/tagging/tagging.htm) in the _Tenable Exposure Management User Guide_.
openapi: 3.0.0
info:
version: 1.0.0
title: Downloads About Tags API
description: 'The Downloads API enables customers to access and download installation and update files for available Tenable products. You can use the API endpoints to list product pages, list downloads available for a specific product, and to download a file. The endpoints can also be used to determine and download the latest version of a file to facilitate the automation of an installation.
**Note:** The Tenable Downloads API uses a different server URL than the Tenable Vulnerability Management API:
`https://www.tenable.com/downloads/api/v2/pages`.
### Authentication
Like the Downloads website, certain files require authentication to download. When files have a `"requires_auth": true` attribute on the product list page, the Downloads API uses bearer token authentication and requires a valid token in the Authorization header to download the file:
```
Authorization: Bearer AbCdEf123456
```
To access or reset your authentication token, navigate to the [Authentication Token](https://www.tenable.com/downloads/api-docs) page.
Examples of product downloads that **do not** require authentication include Nessus and Nessus Agents.'
servers:
- url: https://www.tenable.com/downloads/api/v2
security:
- Bearer: []
tags:
- name: Tags
description: The Tenable Exposure Management tags API enables users to search for their organization's tags. Additionally, API endpoints are provided to retrieve a list of asset and tag properties that can be used as filters on endpoints that support them. For more information, see [Tagging](https://docs.tenable.com/exposure-management/Content/exposure-management/tagging/tagging.htm) in the _Tenable Exposure Management User Guide_.
x-displayName: Tags
paths:
/api/v1/t1/tags/search:
post:
summary: Search tags
operationId: inventory-tag-search
description: 'Returns a list of tags in your organization that match the specified search criteria.
**Caution:** This endpoint is available for use but is currently in beta. The response structure is subject to change as we continue to enhance the data model. <div class="perms-callout">Requires the Basic [16] user role or the `ASSET_INVENTORY.CYBER_ASSET_MANAGEMENT.READ` and `AD.TOGGLE_AD.USE` custom role privileges. See [Roles](doc:roles).</div>'
tags:
- Tags
parameters:
- description: "Specifies extra tag properties to include in the search results. You can provide multiple properties as a comma-separated list. \n\nUse the [List tag properties](ref:inventory-tag-properties-list) endpoint to retrieve a list of valid properties for this parameter. For example, you might include `tag_data_source`, `last_updated`, and `tag_created_by_id` as extra properties."
explode: true
in: query
name: extra_properties
required: false
schema:
example: prop1,prop2,prop3
pattern: ^[a-zA-Z0-9_]+(,[a-zA-Z0-9_]+)*$
type: string
style: form
- description: The starting record to retrieve. If omitted, the default value is `0`.
explode: true
in: query
name: offset
required: false
schema:
default: 0
type: integer
style: form
- description: The number of records to retrieve. If omitted, the default value is `1000`. The maximum value is `1000`.
explode: true
in: query
name: limit
required: false
schema:
default: 1000
maximum: 1000
type: integer
style: form
- description: 'The property and direction to sort the results by, in the format `property:direction`. For example: `tag_name:asc` or `last_updated:desc`'
example: tag_name:asc
explode: true
in: query
name: sort
required: false
schema:
pattern: ^[a-zA-Z0-9_]+:(asc|desc)$
type: string
default: total_weakness_count:desc
style: form
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Inventory_Request-Search-Tags'
required: true
responses:
'200':
description: Returned if the list of assets was retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Inventory_Response-Search-Tags'
examples:
response:
value:
data:
- id: d33ae4f1-cc87-42c0-956a-045aa73c33a6
name: Office
product: TENABLE_IO
asset_count: 5871
weakness_severity_counts:
low: 890
medium: 4534
high: 988
critical: 168
total: 6580
total_weakness_count: 6580
type: DYNAMIC
extra_properties:
tag_data_source: tenable
last_updated: '2023-05-08T14:50:36Z'
aes_average: 147
- id: a48db7c1-9881-4e8c-af66-da38d7ccb7e9
name: Location
product: TENABLE_IO
asset_count: 5871
weakness_severity_counts:
low: 890
medium: 4534
high: 988
critical: 168
total: 6580
total_weakness_count: 6580
type: DYNAMIC
extra_properties:
tag_data_source: tenable
last_updated: '2023-05-08T14:46:13Z'
aes_average: 147
- id: 40d64a4e-715c-4adc-9731-b957c21b7dae
name: Device Type
product: TENABLE_AI
asset_count: 5871
weakness_severity_counts:
low: 890
medium: 4534
high: 988
critical: 168
total: 6580
total_weakness_count: 6580
type: DYNAMIC
extra_properties:
tag_data_source: tenable
last_updated: '2025-03-03T14:23:51Z'
aes_average: 147
- id: 1ad84339-7a44-4fa1-8ccd-3c32a181055a
name: State
product: TENABLE_IO
asset_count: 5871
weakness_severity_counts:
low: 890
medium: 4534
high: 988
critical: 168
total: 6580
total_weakness_count: 6580
type: DYNAMIC
extra_properties:
tag_data_source: tenable
last_updated: '2023-05-08T14:25:32Z'
aes_average: 147
- id: c4d3a3f9-d8f2-4629-ba7b-676a48045ff2
name: City
product: TENABLE_IO
asset_count: 5768
weakness_severity_counts:
low: 889
medium: 4532
high: 984
critical: 168
total: 6573
total_weakness_count: 6573
type: DYNAMIC
extra_properties:
tag_data_source: tenable
last_updated: '2023-05-08T14:05:13Z'
aes_average: 147
- id: cd9caa05-a7df-4ee2-8500-cfd7ba4c8e29
name: Example 1
product: TENABLE_AI
asset_count: 1125
weakness_severity_counts:
low: 847
medium: 4501
high: 950
critical: 168
total: 6466
total_weakness_count: 6466
type: DYNAMIC
extra_properties:
tag_data_source: tenable
last_updated: '2025-03-06T16:46:38Z'
aes_average: 117
- id: c61016c3-4c0d-46ef-91bc-7e249ae3edf4
name: Example 2
product: TENABLE_AI
asset_count: 1125
weakness_severity_counts:
low: 847
medium: 4501
high: 950
critical: 168
total: 6466
total_weakness_count: 6466
type: DYNAMIC
extra_properties:
tag_data_source: tenable
last_updated: '2025-03-06T12:49:10Z'
aes_average: 117
- id: c300c224-7571-4f94-b77b-d1caa334bb3e
name: Example 3
product: TENABLE_AI
asset_count: 147
weakness_severity_counts:
low: 847
medium: 4501
high: 950
critical: 168
total: 6466
total_weakness_count: 6466
type: DYNAMIC
extra_properties:
tag_data_source: tenable
last_updated: '2025-03-12T00:31:07Z'
aes_average: 117
- id: aeffc767-000e-4387-b1b9-e1d3bf596895
name: Example 4
product: TENABLE_AI
asset_count: 147
weakness_severity_counts:
low: 847
medium: 4501
high: 950
critical: 168
total: 6466
total_weakness_count: 6466
type: DYNAMIC
extra_properties:
tag_data_source: tenable
last_updated: '2025-03-13T18:15:17Z'
aes_average: 117
- id: 92c54cee-1b53-4466-9451-724925f50fc9
name: Example 5
product: TENABLE_AI
asset_count: 1125
weakness_severity_counts:
low: 847
medium: 4501
high: 950
critical: 168
total: 6466
total_weakness_count: 6466
type: DYNAMIC
extra_properties:
tag_data_source: tenable
last_updated: '2025-04-30T16:45:36Z'
aes_average: 117
- id: 8c69ceb6-0c62-4050-9016-f872fb92cb3e
name: Example 6
product: TENABLE_AI
asset_count: 1125
weakness_severity_counts:
low: 847
medium: 4501
high: 950
critical: 168
total: 6466
total_weakness_count: 6466
type: DYNAMIC
extra_properties:
tag_data_source: tenable
last_updated: '2025-04-30T16:34:02Z'
aes_average: 117
- id: 73ecd220-f3de-4451-9427-85ad007ed7fd
name: Example 7
product: TENABLE_AI
asset_count: 147
weakness_severity_counts:
low: 847
medium: 4501
high: 950
critical: 168
total: 6466
total_weakness_count: 6466
type: DYNAMIC
extra_properties:
tag_data_source: tenable
last_updated: '2025-03-12T02:58:08Z'
aes_average: 117
- id: 63c2c299-34dd-46a0-be2f-286ef8d34555
name: Example 8
product: TENABLE_AI
asset_count: 1125
weakness_severity_counts:
low: 847
medium: 4501
high: 950
critical: 168
total: 6466
total_weakness_count: 6466
type: DYNAMIC
extra_properties:
tag_data_source: tenable
last_updated: '2025-03-06T11:53:20Z'
aes_average: 117
- id: 401c1515-78af-4117-98b6-c36b8a8427cb
name: Example 9
product: TENABLE_AI
asset_count: 1124
weakness_severity_counts:
low: 846
medium: 4498
high: 949
critical: 167
total: 6460
total_weakness_count: 6460
type: DYNAMIC
extra_properties:
tag_data_source: tenable
last_updated: '2025-03-17T11:54:17Z'
aes_average: 101
- id: 6b58f68b-06d7-431d-9df1-9764a490cc4c
name: Example 10
product: TENABLE_AI
asset_count: 5740
weakness_severity_counts:
low: 849
medium: 4459
high: 981
critical: 166
total: 6455
total_weakness_count: 6455
type: DYNAMIC
extra_properties:
tag_data_source: tenable
last_updated: '2025-03-31T19:19:38Z'
aes_average: 481
pagination:
total: 100
offset: 0
limit: 10
sort:
name: total_weakness_count
order: desc
'400':
description: Returned if your request specified invalid parameters or if your request was improperly formatted.
content:
application/json:
schema:
$ref: '#/components/schemas/Inventory_ErrorResponse'
examples:
response:
value:
error: Bad Request
message: Invalid request payload JSON format
'401':
description: Returned if the API keys specified in your request are invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Inventory_ErrorResponse'
examples:
response:
value:
error: Unauthorized
message: Invalid credentials.
'403':
description: Returned if you do not have permission to search tags.
'429':
description: Returned if you attempt to send too many requests in a specific period of time. For more information, see [Rate Limiting](doc:rate-limiting).
content:
text/html:
examples:
response:
value: "<html>\n\n<head>\n <title>429 Too Many Requests</title>\n</head>\n\n<body bgcolor=\"white\">\n <center>\n <h1>429 Too Many Requests</h1>\n </center>\n <hr>\n <center>nginx</center>\n</body>\n\n</html>"
'500':
description: Returned if an internal error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/Inventory_ErrorResponse'
examples:
response:
value:
statusCode: 500
error: Internal Server Error
message: An internal server error occurred. Please wait a moment and try your request again.
security:
- Inventory_cloud: []
/api/v1/t1/tags/properties:
get:
summary: List tag properties
description: "Returns a list of tag properties that can be used for filters on endpoints that support them. For example, the properties that are returned by this endpoint can be used as filters for the [Search tags](ref:inventory-tag-search) endpoint.\n\n In addition to the tag properties, the results list includes the logical operators you can use with the tag properties along with the supported values.\n\n**Caution:** This endpoint is available for use but is currently in beta. The response structure is subject to change as we continue to enhance the data model. <div class=\"perms-callout\">Requires the Basic [16] user role or the `ASSET_INVENTORY.CYBER_ASSET_MANAGEMENT.READ` and `AD.TOGGLE_AD.USE` custom role privileges. See [Roles](doc:roles).</div>"
operationId: inventory-tag-properties-list
tags:
- Tags
responses:
'200':
description: Returned if the list of tag properties was retrieved successfully.
content:
application/json:
schema:
description: A list of tag properties.
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Inventory_Properties-Object'
examples:
response:
value:
data:
- key: tag_id
readable_name: Tag ID
control:
type: STRING
multiple_allowed: true
regex:
hint: 01234567-abcd-ef01-2345-6789abcdef01
expression: '[0-9a-f]{8}-([0-9a-f]{4}-){3}[0-9a-f]{12}(,[0-9a-f]{8}-([0-9a-f]{4}-){3}[0-9a-f]{12})*'
operators:
- '='
- '!='
- exists
- not exists
sortable: true
filterable: true
description: "# Tag ID \n\n## A way to group assets\n\nIn Tenable Exposure Management, a Tag ID is a unique identifier associated with a Tag. Tags are user-defined labels or markers applied to assets to categorize and organize them based on specific criteria, such as function, location, department, or risk level. \n\nHere's how Tag IDs are used:\n\n- **Grouping and Filtering:** Tag IDs enable you to easily group and filter assets based on shared characteristics. For example, you could use a Tag ID for \"High Risk\" to quickly identify all assets tagged with that specific risk level.\n- **Automation and Reporting:** Tag IDs can be used in automated workflows and reporting to streamline asset management tasks. You can generate reports on assets with specific Tag IDs to gain insights into their security posture or compliance status.\n- **Dynamic Grouping:** Tags and their associated IDs provide a flexible way to group assets dynamically. As asset attributes or risk profiles change, you can easily update their tags to reflect their current status. \n"
- key: tag_data_source
readable_name: Tag Data Source
control:
type: STRING
multiple_allowed: false
regex:
hint: ''
expression: .*
operators:
- contains
- not contains
- '='
- '!='
- exists
- not exists
sortable: true
filterable: true
description: "# Tag Data Source \n## Where the tag information comes from\nTag data sources represent the origin or method by which tags are applied to assets within Tenable Exposure Management. Understanding the source of your tags is crucial for managing and interpreting tag information effectively.\n\nHere's a breakdown of tag data sources:\n\n- **Manual**: Tags added manually by users through the Tenable Exposure Management interface. This allows for flexible and customized tagging based on specific needs.\n- **Integration**: Tags automatically applied based on data fetched from integrated external systems. This ensures consistency and reduces manual effort.\n- **Rule**: Tags dynamically assigned based on predefined rules and conditions within Tenable Exposure Management. This enables automated tagging based on asset attributes or behaviors.\n- **Bulk**: Tags applied in bulk to multiple assets simultaneously, often using CSV imports or API calls. This streamlines tagging for large numbers of assets. \n"
- key: last_updated
readable_name: Last Updated
control:
type: DATE
multiple_allowed: false
regex:
hint: timestamp
expression: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
operators:
- '='
- '>'
- <
- between
- exists
- not exists
- older than
- newer than
- within last
sortable: true
filterable: true
description: "# Last Updated \n\n## Date of the last tag modification\n\nThe \"Last Updated\" field in Tenable Exposure Management refers to the date and time when a specific tag associated with an asset was last modified. This timestamp helps track the recency of tag-related changes and provides insights into the asset's tagging history.\n\nHere's a breakdown of its significance:\n\n- **Tracking Tag Changes**: It allows administrators to see when a particular tag was added, removed, or modified for an asset.\n- **Auditing and Compliance**: Helps in maintaining an audit trail of tag-related activities, which can be crucial for compliance reporting.\n- **Asset Management**: Provides context about the asset's categorization and management over time. \n- **Filtering and Reporting**: Enables users to filter assets based on the last updated date of specific tags, aiding in identifying recently tagged or untagged assets. \n"
- key: tag_name
readable_name: Tag Name
control:
type: STRING
multiple_allowed: false
regex:
hint: ''
expression: .*
operators:
- contains
- not contains
- '='
- '!='
- exists
- not exists
sortable: true
filterable: true
description: "# Tag Name \n## A label assigned to assets for categorization\nTag Name allows users to categorize and group assets based on specific criteria, such as department, location, sensitivity of data stored, or compliance requirements.\n\nHere are some key points to understand about Tag Name in the context of Cyber Asset Management:\n\n- **Organization and Filtering**: Tag Name enables efficient organization and filtering of assets within Tenable Exposure Management, making it easier to locate and manage specific groups of assets.\n- **Contextual Information**: Tags provide valuable contextual information about assets, aiding in risk assessment, vulnerability management, and incident response efforts.\n- **Automation and Reporting**: Tags can be used to automate tasks, such as applying security policies or generating reports based on specific asset groups.\n- **Flexibility and Customization**: Tenable Exposure Management allows users to create and assign custom tags based on their organization's specific needs and terminology.\n- **Improved Asset Visibility**: By using meaningful Tag Names, organizations can gain a clearer understanding of their asset inventory and potential security risks.\n"
- key: tag_description
readable_name: Tag Description
control:
type: STRING
multiple_allowed: false
regex:
hint: ''
expression: .*
operators:
- contains
- not contains
- '='
- '!='
- exists
- not exists
sortable: true
filterable: true
description: "# Tag Description \n\n## A text used to categorize Assets\n\nA tag description provides additional context and information about a specific tag used for categorizing and organizing assets within Tenable Exposure Management. It helps users understand the purpose and meaning of the tag, making it easier to search, filter, and manage assets effectively.\n\nHere are some key points to understand about tag descriptions:\n\n- **Clarity and Conciseness**: Tag descriptions should be clear, concise, and easy to understand, providing a brief explanation of the tag's purpose.\n- **Relevance**: The description should accurately reflect the tag's intended use and the types of assets it's associated with.\n- **Contextual Information**: It can include details about the tag's scope, criteria for applying the tag, or any specific conventions used.\n- **Examples**: Providing examples of assets or asset attributes that would typically receive the tag can be helpful for users. \n"
- key: product
readable_name: Product
control:
type: STRING
multiple_allowed: true
selection:
- name: TENABLE_AI
value: TENABLE_AI
deprecated: false
- name: TENABLE_IO
value: TENABLE_IO
deprecated: false
operators:
- contains
- not contains
- '='
- '!='
- exists
- not exists
sortable: true
filterable: true
description: "# Product \n## A way to group assets by software\nIn Tenable Exposure Management, a Tag is a way to categorize and group assets based on shared characteristics. One type of tag is a \"Product,\" which allows you to associate assets with specific software products installed on them. \n\nHere's how it works:\n\n- **Tagging Assets:** When you discover assets in your environment, Cyber Asset Management automatically identifies the software installed on them. You can then create \"Product\" tags and assign them to assets based on the detected software.\n- **Grouping and Filtering:** Once tagged, you can easily group and filter assets based on the software products they have in common. For example, you can create a group of all assets with a specific version of a software product to identify potential vulnerabilities.\n- **Streamlining Management:** By using \"Product\" tags, you can streamline asset management tasks, such as vulnerability remediation, patch management, and software inventory. \n"
- key: tag_type
readable_name: Tag Type
control:
type: STRING
multiple_allowed: false
regex:
hint: ''
expression: .*
operators:
- contains
- not contains
- '='
- '!='
- exists
- not exists
sortable: true
filterable: true
description: "# Tag Type \n\n## A label category for assets\n\nA tag type is a user-defined category or classification that helps organize and group tags within Cyber Asset Management. It provides a structured way to manage and apply tags to assets, making it easier to search, filter, and analyze asset data based on specific criteria.\n\nHere are some key points to understand about tag types:\n\n- **Organization**: Tag types bring order to your tags, preventing a chaotic and unmanageable collection.\n- **Standardization**: They enforce consistency in tagging, ensuring that similar assets are tagged uniformly.\n- **Filtering and Reporting**: Tag types simplify asset searching and filtering, allowing you to quickly locate assets with specific tags.\n- **Automation**: Tag types can be used to automate tagging processes, such as automatically applying tags based on asset attributes or events.\n- **Examples**: Common tag types include \"Environment\" (e.g., Production, Development, Testing), \"Location\" (e.g., New York, London, Tokyo), \"Department\" (e.g., Finance, Marketing, IT), and \"Compliance\" (e.g., PCI DSS, HIPAA, GDPR).\n"
- key: tag_category_id
readable_name: Tag Category ID
control:
type: STRING
multiple_allowed: false
regex:
hint: ''
expression: .*
operators:
- contains
- not contains
- '='
- '!='
- exists
- not exists
sortable: true
filterable: true
description: "# Tag Category ID \n\n## A unique identifier for a group of tags.\n\nIn Tenable Exposure Management, tags are used to categorize and organize assets based on various criteria, such as function, location, or sensitivity. To manage tags effectively, they are grouped into categories. Each tag category is assigned a unique ID, known as the Tag Category ID. This ID helps in filtering and searching for assets based on specific tag categories.\n\nHere's a breakdown:\n\n- **Tag:** A label assigned to assets to categorize them based on specific criteria.\n- **Tag Category:** A group of related tags that share a common theme or purpose.\n- **Tag Category ID:** A unique identifier assigned to each tag category for efficient management and filtering. \n"
- key: tag_category_name
readable_name: Tag Category Name
control:
type: STRING
multiple_allowed: false
regex:
hint: ''
expression: .*
operators:
- contains
- not contains
- '='
- '!='
- exists
# --- truncated at 32 KB (183 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tenable/refs/heads/main/openapi/tenable-tags-api-openapi.yml