Manage provider versions API reference

Use the provider version management API endpoints to list, add, and update tags for provider versions in your organization's registry.

List all tags for a provider version

Use this endpoint to list all tags assigned to a provider version.

GET /api/v2/registry-provider-versions/:provider_version_id/tag-bindings

Parameter	Description
`:provider_version_id`	The specific provider version ID whose tags you want to list.

Status	Response	Reason
200	JSON API document	The request was successful.
401	JSON API error object	User unauthorized.
404	JSON API error object	The provider version does not exist.

Sample request

curl \
  --request GET \
  --header "Authorization: Bearer $TOKEN" \
  https://app.terraform.io/api/v2/registry-provider-versions/provver-E94qRpUHFZezgEWC/tag-bindings

Sample response

{
  "data": [
    {
      "id": "tb-LDojeUQnBPGYbDdA",
      "type": "tag-bindings",
      "attributes": {
        "key": "environment",
        "value": "dev",
        "created-at": "2026-07-15T20:11:56.432Z"
      }
    },
    {
      "id": "tb-HPnKh5kf4TiGYMVr",
      "type": "tag-bindings",
      "attributes": {
        "key": "environment",
        "value": "testing",
        "created-at": "2026-07-15T20:11:56.437Z"
      }
    }
  ],
  "links": {
    "target": "/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/test-provider/versions?version=5.14.0"
  }
}

Add or update tags for a provider version

Send a PATCH request to the following endpoint to add or update tags for a provider version in your organization's registry.

To remove tags from a provider version, omit the tag keys and values from the request body when sending the PATCH request.

PATCH /api/v2/organizations/:organization_name/registry-providers/:registry_name/:namespace/:provider_name/versions/:provider_version

Parameter	Description
`:organization_name`	The name of the organization the provider belongs to.
`:registry_name`	Either `public` or `private`.
`:namespace`	The namespace of the provider.
`:provider_name`	The name of the provider whose version you want to tag.
`:provider_version`	The provider version you want to add or update a tag for.

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 provider 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

This PATCH endpoint requires a JSON object with the following properties as a request payload.

Key path	Type	Description
`data.type`	string	Must be `"registry-provider-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-provider-versions",
    "relationships": {
      "organization": {
        "data": {
          "type": "organizations",
          "id": "hashicorp"
        }
      },
      "tag-bindings": {
        "data": [
          {
            "type": "tag-bindings",
            "attributes": {
              "key": "environment",
              "value": "dev"
            }
          },
          {
            "type": "tag-bindings",
            "attributes": {
              "key": "environment",
              "value": "testing"
            }
          }
        ]
      }
    }
  }
}

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/organizations/hashicorp/registry-providers/private/hashicorp/test-provider/versions/0.0.4

Sample response

{
  "data": {
    "id": "provver-E94qRpUHFZezgEWC",
    "type": "registry-provider-versions",
    "attributes": {
      "version": "0.0.4",
      "created-at": "2026-02-24T02:45:50.571Z",
      "updated-at": "2026-02-24T02:45:50.571Z",
      "key-id": "34365D9472D7468F",
      "protocols": [
        "5.0"
      ],
      "permissions": {
        "can-delete": true,
        "can-upload-asset": true
      },
      "shasums-uploaded": false,
      "shasums-sig-uploaded": false
    },
    "relationships": {
      "registry-provider": {
        "data": {
          "id": "prov-kYepEWv1vNWdKAsM",
          "type": "registry-providers"
        }
      },
      "tag-bindings": {
        "links": {
          "related": "/api/v2/registry-provider-versions/provver-E94qRpUHFZezgEWC/tag-bindings"
        }
      },
      "registry-provider-platforms": {
        "data": [],
        "links": {
          "related": "/api/v2/organizations/hashicorp/registry-providers/private/hashicorp/test-provider/versions/5.14.0/platforms"
        }
      }
    },
    "links": {
      "shasums-upload": "https://archivist.terraform.io/v1/object/dmF1bHQ6djU6bjNHZW9jV3NhRUxjZGJma1",
      "shasums-sig-upload": "https://archivist.terraform.io/v1/object/dmF1bHQ6djU6WnBVNlJ3Y2RzcEgxUHB"
    }
  }
}