# Tagging Only available in Sonatype Nexus RepositoryTM Pro. Interested in a free trial? [Start here](/content/products/repository-pro/trial/index.html). Available only in Nexus Repository Pro, tagging provides the ability to mark a set of components with a tag so that they can be logically associated with each other. The most common scenarios for using tags include the following: - A CI build ID for a project (e.g., project-abc-build-142). - A higher-level release train is when you are coordinating multiple projects together as a single unit (e.g., release-train-13). The [Staging](https://help.sonatype.com/en/staging.html "Staging") feature uses tagging extensively. **Note** Tags are applied at the component level and not to individual assets. ## Endpoints Tagging capabilities are available via a REST API. Non-administrator users will need the respective _nx-tags_ [privileges](https://help.sonatype.com/en/privileges.html "Privileges") to perform the curl. ### Add Tag ``` POST /service/rest/v1/tags ``` This endpoint allows you to create a tag. Here is a simple example: ``` curl -u admin:admin123 -X POST --header 'Content-Type: application/json' http://127.0.0.1:8081/service/rest/v1/tags \ -d '{ "name": "project-abc-142", "attributes": { "jvm": "9", "built-by": "jenkins" } }' ``` The `name` field cannot exceed 256 characters and can only contain letters, numbers, underscores, hyphens, and dots and cannot start with an underscore or dot. The `attributes` field can contain any valid JSON data that might assist you. There is a maximum size of 20k for the `attributes` field. The response contains two additional timestamp fields to represent when the tag was first created and last updated. These two fields are set automatically and are ignored if sent in a `POST` or `PUT`. **Example Response** ``` { "name": "project-abc-142", "attributes": { "jvm": "9", "built-by": "jenkins" }, "firstCreated": "2017-06-12T22:42:55.019+0000", "lastUpdated": "2017-06-12T22:42:55.019+0000" } ``` ### List Tags ``` GET /service/rest/v1/tags ``` This endpoint allows us to iterate through a listing of all the tags. This endpoint has no parameters: ``` curl -u admin:admin123 -X GET http://127.0.0.1:8081/service/rest/v1/tags ``` This will typically produce a response that is the first page of many tags: **Example Response** ``` { "items": [\ {\ "name": "project-abc-142",\ "attributes": {\ "jvm": "9",\ "built-by": "jenkins"\ },\ "firstCreated": "2017-06-12T22:42:55.019+0000",\ "lastUpdated": "2017-06-12T22:42:55.019+0000"\ },\ {\ "name": "project-abc-456",\ "attributes": {\ "jvm": "9",\ "built-by": "jenkins"\ },\ "firstCreated": "2017-06-13T22:24:55.019+0000",\ "lastUpdated": "2017-06-13T22:24:55.019+0000"\ }\ ], "continuationToken": null } ``` This endpoint uses a pagination strategy that can be used to iterate through all the tags if desired. Note that the ordering of the tags is consistent across multiple queries but it is not alphabetical. **Note** It is also possible to see components associated with a given tag via the UI. You can do this by navigating to the _Tags_ section of the _Browse_ menu, selecting a tag, and clicking _Find Tagged Components._ This same behavior is doable by doing a custom search using the _Tag_ criteria. ### Get Tag ``` GET /service/rest/v1/tags/{tagName} ``` This endpoint allows us to get details about an individual tag. ``` curl -u admin:admin123 -X GET http://127.0.0.1:8081/service/rest/v1/tags/project-abc-142 ``` **Example Response** ### Update Tag ``` PUT /service/rest/v1/tags/{tagName} ``` This endpoint allows us to update the attributes of a single tag. Note that you cannot change the tag name or timestamp fields. ``` curl -u admin:admin123 -X PUT --header 'Content-Type: application/json' http://127.0.0.1:8081/service/rest/v1/tags/project-abc-142 -d '{ "attributes": { "jvm": "9", "built-by": "bob" } }' ``` **Example Response** ``` { "name": "project-abc-142", "attributes": { "jvm": "9", "built-by": "bob" }, "firstCreated": "2017-06-12T22:42:55.019+0000", "lastUpdated": "2017-06-13T21:42:55.019+0000" } ``` ### Associate Components with a Tag ``` POST /service/rest/v1/tags/associate/{tagName} ``` This endpoint allows you to search for components and associate them with an existing tag. Note that this endpoint does not create a tag if it does not exist. ``` curl -u admin:admin123 -X POST 'http://127.0.0.1:8081/service/rest/v1/tags/associate/project-abc-142?repository=my-company&group=com.mycompany&name=project-abc&version=2.1.1' ``` This example shows a search within a repository for a specific artifact using the group, name, and version. See [Search API](https://help.sonatype.com/en/search-api.html "Search API") for details on how to search for components. **Example Response** ``` { "status": 200, "message": "Association successful", "data": { "components associated": [\ {\ "name": "project-abc",\ "group": "com.mycompany",\ "version": "2.1.0"\ }\ ] } } ``` The response contains a collection of all the components that were successfully associated with the tag. This response can be used to assert that the association worked as expected. #### Wait Query Parameter When associating a tag with a component using the Tag Association REST API, the optional wait query parameter controls whether the API waits for the repository search index to update before returning a response. Because tags are indexed asynchronously, there may be a short delay before a newly associated tag becomes searchable. The wait parameter determines whether the request waits for indexing to complete. ##### Parameter | Parameter | Type | Default | Description | | --- | --- | --- | --- | | `wait` | boolean | true | Determines whether the API waits for search indexing to complete before returning the response. | ##### Behaviour | Value | Behavior | Recommended Use | | --- | --- | --- | | `wait=true` | Waits approximately 2 seconds for the search index to update before returning. Tags are immediately searchable once the API returns 200 OK. | Recommended for most use cases, including automation scripts and single tagging operations. | | `wait=false` | Returns immediately (typically under 100 ms). Tag indexing occurs asynchronously and search results may take approximately 2–7 seconds to reflect the change. | Recommended for bulk tagging operations where immediate searchability is not required. | ##### Examples **Default behavior (wait=true)** The API waits for indexing to complete before returning. ``` POST /service/rest/v1/tags/associate/my-tag?repository=repo&name=component ``` **Fast mode (wait=false)** Returns immediately while indexing continues asynchronously. ``` POST /service/rest/v1/tags/associate/my-tag?repository=repo&name=component&wait=false ``` **Important** - The default value for `wait` is true. - Using `wait=true` ensures that tags can be immediately used in search queries or tag-based operations after the API request completes. - Using `wait=false` improves performance when associating tags in bulk operations, but newly associated tags may not be immediately searchable. ### Tagging During Component Upload You can also tag components by including a `tag` when exercising the upload component REST endpoint provided by the Components API. The example below specifies the `tag` to associate with the component being uploaded by adding `"-F tag=project-abc-142"` to the component upload call. You can also upload and tag components when uploading through the user interface. | | | --- | | `curl -v -u admin:admin123 -X POST 'http://localhost:8081/service/rest/v1/components?repository=my-company' \ ` -F groupId=com.mycompany \ ` -F artifactId=project-abc \ ` -F version=2.1.1 \ ` -F asset1=@project-abc-2.1.1.jar \ ` -F asset1.extension=jar \ ` -F tag=project-abc-142` | ### Disassociate Components from a Tag ``` DELETE /service/rest/v1/tags/associate/{tagName} ``` This endpoint allows you to search for components and disassociate them from a tag. Note that this endpoint is similar to the association endpoint, but it uses a `DELETE` instead of a `POST`. ``` curl -u admin:admin123 -X DELETE 'http://127.0.0.1:8081/service/rest/v1/tags/associate/project-abc-142?repository=my-company&group=com.mycompany&name=project-abc&version=2.1.1' ``` **Example Response** ``` { "status": 200, "message": "Disassociation successful", "data": { "components disassociated": [\ {\ "name": "project-abc",\ "group": "com.mycompany",\ "version": "2.1.1"\ }\ ] } } ``` ## Security Tagging is controlled by the following privileges. | Privilege | What it Allows | | --- | --- | | `nx-tags-all` | All tagging actions. | | `nx-tags-associate` | View tags and associate them to components located in repositories to which the user has browse privileges. | | `nx-tags-create` | View and create tags. | | `nx-tags-delete` | View and delete tags. | | `nx-tags-disassociate` | View tags and disassociate them from components located in repositories to which the user has browse privileges. | | `nx-tags-read` | Allows the viewing of tags. | | `nx-tags-update` | View and update tags. | For associate and disassociate, the respective user will also need the ability to browse the components, defined by the nx-repository-view browse privilege for the respective repository. ## Cleanup Task Having a CI system automatically tag every build can result in an overabundance of tags. The _Admin - Cleanup tags_ task allows administrators to delete tags based on the following criteria: - Age (in days) of when the tag was first created (default is 0 days). - Age (in days) of when the tag was last modified (default is 0 days). - A regular expression on the tag name (e.g. project-abc-.*). If an administrator selects multiple options, the tag must meet both criteria. Additionally, you can select to delete the components associated with the tag; this option can be restricted to a specific repository or format. **Warning** In situations where a component has two associated tags and the tag cleanup task is configured to delete the components, the system will delete that component even when the cleanup task only matches on one of the tags. For example, if component A is tagged with "build-123" and "dev-build-123" and the tag cleanup task is configured to clean up tag "dev-build-123" AND delete components associated with it, it will delete component A. The component also being tagged "build-123" will not prevent the deletion. The task log for the _Admin - Cleanup tags_ task contains a list of the deleted tags and components. See the task logging section on the System Configuration page for details. ## Best Practices The following are some best practice recommendations for using tagging: - Use short tag names and attributes to maximize the performance of tag-related operations and storage utilization. Maintaining a large number of tags with attributes of maximum allowable size (20k) could result in undesirable performance degradation. - Proactively use the _Admin - Cleanup tags_ task to clean up unused tags. The _Admin - Cleanup tags_ task provides configuration options to support routine removal of aged or unused tags and the associated components (if desired). - Use a tag naming scheme that will ensure the uniqueness of created tags and prevent naming collisions and potential interruptions to CI pipeline workflows.