Tagging via API

Tenable exposes tag management endpoints for Tenable One Vulnerability Management, Tenable One, and Tenable One Attack Surface Management through the Tenable REST API. Automation via the API lets you integrate tag management into CI/CD pipelines, CMDB synchronization workflows, and scripted bulk operations that would be impractical through the UI.

The base URL for all Tenable cloud API calls is https://cloud.tenable.com. All requests require an X-ApiKeys authentication header.

X-ApiKeys: accessKey=<access_key>;secretKey=<secret_key>

Generate API keys under Settings → My Account → API Keys in Tenable One Vulnerability Management.

Full interactive reference documentation is available at developer.tenable.com/reference.

Note: Tenable Security Center uses a separate on-premises API. Tenable Security Center Asset Tags are managed via the Security Center REST API documented at docs.tenable.com/security-center. Tenable Security Center Director shares the same API surface as Tenable Security Center but targets the Director host.

Tenable One Vulnerability Management — Tags API

The Tenable One Vulnerability Management Tags API uses a two-tier model: categories and values. Create the category first, then create one or more values within it. Tag rules (for dynamic tags) are defined as part of the tag value.

Required role: Scan Manager [40] or higher for create/update/delete operations. Standard users can read.

Category Endpoints

Operation Method Endpoint
Create tag category POST /tags/categories
List tag categories GET /tags/categories
Get category details GET /tags/categories/{category_uuid}
Update tag category PUT /tags/categories/{category_uuid}
Delete tag category DELETE /tags/categories/{category_uuid}

Create category — example request body: 

{
  "name": "Environment",
  "description": "Deployment environment classification"
}

Create category — example response (truncated): 

{
  "uuid": "a1b2c3d4-...",
  "name": "Environment",
  "description": "Deployment environment classification",
  "created_at": "2026-01-15T10:00:00Z",
  "updated_at": "2026-01-15T10:00:00Z"
}
Caution: Deleting a category is irreversible. It removes the category and all associated values from every asset in your instance. The UUID of a deleted category cannot be reused.

Tag Value Endpoints

Operation Method Endpoint
Create tag value POST /tags/values
List tag values GET /tags/values
Get tag value details GET /tags/values/{value_uuid}
Update tag value PUT /tags/values/{value_uuid}
Delete tag value DELETE /tags/values/{value_uuid}
Bulk delete tag values POST /tags/values/delete

Create a static (manual) tag value — example request body: 

{
  "category_uuid": "a1b2c3d4-...",
  "value": "Production",
  "description": "Production environment assets",
  "type": "static"
}

Create a dynamic tag value with rules — example request body: 

{
  "category_uuid": "a1b2c3d4-...",
  "value": "AWS-Production",
  "description": "Auto-tag AWS production assets",
  "type": "dynamic",
  "filters": {
    "asset": {
      "and": [
        {
          "field": "aws_region",
          "operator": "eq",
          "value": "us-east-1"
        },
        {
          "field": "sources",
          "operator": "eq",
          "value": ["AWS"]
        }
      ]
    }
  }
}

Asset Tag Assignment Endpoints

Operation Method Endpoint
List tags for an asset GET /assets/{asset_uuid}/tags
Add or remove asset tags POST /tags/assets/assignments
List asset tag filters GET /tags/filters/assets
List tag exclusions GET /tags/exclusions

Add or remove tags from assets — example request body: 

{
  "action": "add",
  "assets": [
    { "id": "asset-uuid-1" },
    { "id": "asset-uuid-2" }
  ],
  "tags": [
    { "id": "value-uuid-1" }
  ]
}

Set "action" to "remove" to remove the specified tags from the specified assets.

Note — API/UI Filter Divergence: The GET /tags/filters/assets endpoint (V1) does not return every filter type available in the Tagging UI, including cloud resource tag filters (Resource Tags (By Key) and Resource Tags (By Value)). If a filter you rely on in the UI is missing from this endpoint's response, build or verify that rule through the UI rather than assuming API parity.

Recommended API Workflow

To create and assign a tag via the API:

  1. Call GET /tags/categories to retrieve existing categories and their UUIDs.

  2. If the category doesn't exist, call POST /tags/categories to create it. Note the returned uuid.

  3. Call POST /tags/values with the category UUID to create the tag value, specifying type: "static" or type: "dynamic".

  4. For static tags, call POST /tags/assets/assignments to assign the tag to specific assets by their UUIDs.

  5. For dynamic tags, the rules engine evaluates asset membership automatically — no manual assignment step is required.

Tenable One — Tags API

The Tenable One Inventory API provides endpoints to search and inspect tags within the Tenable One platform. These endpoints work across all tag sources visible in Tenable One — Tenable One Vulnerability Management tags, Tenable One native tags, and External Tags.

Required role: Any authenticated Tenable One user can read. Tag creation and management for Tenable One Tags is done through the Tenable One Vulnerability Management Tags API (above) or the Tenable Exposure Management UI.

Operation Method Endpoint
Search tags POST /inventory/tag/search
List tag properties GET /inventory/tag/properties

Search tags — example request body: 

{
  "query": {
    "field": "tag.category",
    "operator": "eq",
    "value": "Environment"
  },
  "limit": 100,
  "offset": 0
}

Use GET /inventory/tag/properties to discover the queryable fields and their valid operators before building search queries.

Note: The Tenable One Tags API is read-oriented. To create or modify tags that appear in Tenable One, use the Tenable One Vulnerability Management Tags API or the Tenable Exposure Management UI. External Tags (from Cloud Security, Identity Exposure, or third-party integrations) cannot be created or modified via the Tenable developer API.

Tenable One Attack Surface Management — Tags API

The Tenable One Attack Surface Management Tags API uses a different model from the Tenable One Vulnerability Management Tags API. Tenable One Attack Surface Management tags (referred to internally as "portfolios") have a name and a value type — they are not structured as Category:Value pairs. Tags are managed globally within an inventory and can be assigned to assets individually or in bulk using filters.

Base URL for Tenable One Attack Surface Management API calls:https://cloud.tenable.com (same host, different path prefixes).

Operation Method Endpoint
Get all tags from store GET /asm/v1/portfolios
Add a new tag POST /asm/v1/portfolio/create
Edit tag by ID POST /asm/v1/portfolio/edit
Delete tag from store POST /asm/v1/portfolio/delete
Search tags by name POST /asm/v1/portfolio/search
Add assets to tags POST /asm/v1/portfolios/assets/add
Remove assets from tags POST /asm/v1/portfolios/assets/remove
Add assets to tags (by filter) POST /asm/v1/portfolios/assets/add/filter
Remove assets from tags (by filter) POST /asm/v1/portfolios/assets/remove/filter

Create an Tenable One Attack Surface Management tag — example request body: 

{
  "name": "Business Unit",
  "type": "keyword"
}

Valid type values are: no_value, keyword, number, cost, percentage, boolean.

Add assets to a tag using a filter — example request body: 

{
  "portfolio_ids": ["tag-uuid-1"],
  "inventory_id": "your-inventory-uuid",
  "filter": {
    "field": "domain",
    "type": "contains",
    "value": "example.com"
  }
}
Caution: Deleting an Tenable One Attack Surface Management tag via /asm/v1/portfolio/delete removes the tag and all its associations from every asset across the inventory. This operation cannot be undone.

Tenable One Attack Surface Management API Authentication

The Tenable One Attack Surface Management API supports two authentication methods:

  • Tenable API keys — Use the same X-ApiKeys header as the Tenable One Vulnerability Management API, if your Tenable One Attack Surface Management instance is linked to a Tenable cloud account.
  • Bearer token — Some Tenable One Attack Surface Management API calls use an Authorization: Bearer <token> header. Obtain the token via the Tenable One Attack Surface Management login endpoint.

Refer to the Tenable One Attack Surface Management API reference for the authentication method applicable to each endpoint.

Tenable Security Center — Asset Tags API

Tenable Security Center provides a REST API for managing its resources, including Asset Tags. Asset Tags are managed as asset resources — the same endpoint family used for the typed asset lists described in Tags in Tenable Security Center.

Host: Your on-premises Tenable Security Center hostname (for example, https://sc.example.com).

Authentication: Tenable Security Center uses session-based authentication via POST /rest/token or API key authentication (Tenable Security Center 5.13+) via the X-APIKey header.

To create a Static Asset Tag, use the following request.

POST /rest/asset
{
  "name": "PCI-Scope",
  "type": "static",
  "definedIPs": "10.0.0.0/24"
}

To create a Dynamic Asset Tag, supply rule-based condition statements instead of a fixed IP list.

POST /rest/asset
{
  "name": "PCI-Scope-Dynamic",
  "type": "dynamic",
  "rules": [
    { "filterName": "ip", "operator": "=", "value": "10.0.0.0/24" }
  ]
}

Other supported type values include dnsname, ldapquery, combination, and upload (Import Asset Tags). Update an existing Asset Tag with PATCH /rest/asset/{id}, remove one with DELETE /rest/asset/{id}, and recalculate a Dynamic or LDAP Query Asset Tag's membership on demand with POST /rest/asset/{id}/refresh.

Full Tenable Security Center REST API documentation is available at docs.tenable.com/security-center.

Note: Tenable Security Center Director uses the same REST API surface as Tenable Security Center, targeting the Director host. Asset Tag management via API against Tenable Security Center Director follows the same pattern described above.

Tenable Security Center — Labels API

Tenable Security Center also has a separate, unrelated Labels feature — a free-form descriptor you can set on an asset, scan policy, credential, or query. Labels are managed through object-level endpoints — you set the label when creating or updating an object, rather than through a dedicated labels endpoint.

Labels are set via the tags field on the relevant object. For example, to set a label on an asset, use the following request.

PATCH /rest/asset/{id}
{
  "tags": "PCI-Scope"
}

And to set a label on a scan policy, use the following request.

PATCH /rest/policy/{id}
{
  "tags": "PCI-Scope"
}

Labels are stored as plain strings. Each object supports a single label string. To retrieve objects by label, use the filter query parameter.

GET /rest/asset?filter=tags%3APCI-Scope

To retrieve the full list of unique Labels in use, use GET /rest/asset/tag.

Note: Label management via API against Tenable Security Center Director follows the same pattern described above, targeting the Director host.

Additional Resources

For the complete API reference, see developer.tenable.com/reference/navigate.