Manage component versions API reference
Use the Stack component configuration version management API endpoints to list, add, and update tags for component configuration versions in your organization's registry.
List tags
Call the following endpoint to list all tags assigned to a registry component version.
GET /api/v2/registry-component-versions/:component_version_id/tag-bindings
| Parameter | Description |
|---|---|
:component_version_id | The specific component configuration version id whose tags you want to list. |
Response codes
| Status | Response | Reason |
|---|---|---|
| 200 | JSON API document | The request was successful. |
| 401 | JSON API error object | User unauthorized. |
| 404 | JSON API error object | The component configuration version does not exist. |
Sample request
curl \
--request GET \
--header "Authorization: Bearer $TOKEN" \
https://app.terraform.io//api/v2/registry-component-versions/compver-JRtoeJbP5R4Fv4qn/tag-bindings
Sample response
{
"data": [
{
"id": "tb-XHJG1sCBejBGrbtS",
"type": "tag-bindings",
"attributes": {
"key": "environment",
"value": "staging",
"created-at": "2026-07-15T20:42:14.882Z"
}
},
{
"id": "tb-k36uoJvKYzTWS1KG",
"type": "tag-bindings",
"attributes": {
"key": "environment",
"value": "dev",
"created-at": "2026-07-15T20:42:14.887Z"
}
}
],
"links": {
"target": "/api/v2/registry-components/comp-Xyow7YbAyBDMkax1/versions/0.0.4"
}
}
Add or update tags
Send a PATCH request to the following endpoint to add, update, or remove tags for a registry component version in your organization's registry.
The request replaces the existing tags with tag keys and values specified in the request body. To remove specific tags, specify only the tag keys and values you want to keep. A request body with empty key and value attributes removes all tags.
PATCH /api/v2/registry-components/:component_id/versions/:component_version
| Parameter | Description |
|---|---|
:component_id | The id of the registry component whose version you want to tag. |
:component_version | The component configuration version you want to add or update a tag for. |
Response codes
| Status | Response | Reason |
|---|---|---|
| 200 | JSON API document | Successfully added or updated the tag binding. |
| 400 | JSON API error object | Request body cannot be parsed. |
| 401 | JSON API error object | User not authorized. |
| 404 | JSON API error object | The component configuration version does not exist. |
| 422 | JSON API error object | HCP Terraform can't process the content because the tag key or value format is incorrect. |
Request body
PATCH requests require a JSON object with the following properties as a request payload.
| Key path | Type | Default | Description |
|---|---|---|---|
data.type | string | Must be "registry-component-versions". | |
data.relationships.tag-bindings.data.attributes.key | string | The tag key. | |
data.relationships.tag-bindings.data.attributes.value | string | The tag value. |
Sample payload
{
"data": {
"type": "registry-component-versions",
"relationships": {
"tag-bindings": {
"data": [
{
"type": "tag-bindings",
"attributes": {
"key": "environment",
"value": "staging"
}
},
{
"type": "tag-bindings",
"attributes": {
"key": "environment",
"value": "dev"
}
}
]
}
}
}
}
Sample request
curl \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/vnd.api+json" \
--request PATCH \
--data @payload.json \
https://app.terraform.io/api/v2/registry-components/comp-Xyow7YbAyBDMkax1/versions/0.0.4
Sample response
{
"data": {
"id": "compver-JRtoeJbP5R4Fv4qn",
"type": "registry-component-versions",
"attributes": {
"source": "github",
"status": "completed",
"version": "0.0.4",
"readme": "# pet-nulls-stack readme",
"description": "A Terraform Stack using two components, two environments, and the random_pet and null_resource resources.",
"published-at": "2026-05-20T04:26:56.017775Z",
"error-message": null,
"source-url": "https://github.com/userhere/pet-nulls-stack"
},
"relationships": {
"registry-component": {
"links": {
"related": "/api/v2/registry-components/comp-Xyow7YbAyBDMkax1"
}
},
"resources": {
"links": {
"related": "/api/v2/registry-components/comp-Xyow7YbAyBDMkax1/versions/0.0.4/resources"
}
},
"variables": {
"links": {
"related": "/api/v2/registry-components/comp-Xyow7YbAyBDMkax1/versions/0.0.4/variables"
}
},
"outputs": {
"links": {
"related": "/api/v2/registry-components/comp-Xyow7YbAyBDMkax1/versions/0.0.4/outputs"
}
},
"providers": {
"links": {
"related": "/api/v2/registry-components/comp-Xyow7YbAyBDMkax1/versions/0.0.4/providers"
}
},
"tag-bindings": {
"links": {
"related": "/api/v2/registry-component-versions/compver-JRtoeJbP5R4Fv4qn/tag-bindings"
}
}
},
"links": {
"self": "/api/v2/registry-components/compver-JRtoeJbP5R4Fv4qn/versions/0.0.4",
"upload": "https://archivist.terraform.io/v1/object/dmF1bHQ6djU6cWtBcDF6aGpKeC"
}
}
}