Organization tags API reference

This API returns the list of tags used in workspaces across the organization. Tags can be added to this pool via workspaces. Tags deleted here will be removed from all other workspaces. Tags can be added, applied, removed and deleted in bulk.

Tags are subject to the following rules:

Workspace tags or tags must be one or more characters, have a 255 character limit, and can include letters, numbers, colons, hyphens, and underscores.
You can create tags for a workspace using the user interface or the API. After you create a tag, you can assign it to other workspaces in the same organization.
You cannot create tags for a workspace using the CLI.
You cannot set tags at the project level, so there is no tag inheritance from projects to workspaces.

GET /organizations/:organization_name/tags

Parameter	Description
`:organization_name`	The name of the organization to list tags from

Query Parameters

This endpoint supports pagination with standard URL query parameters; remember to percent-encode [ as %5B and ] as %5D if your tooling doesn't automatically encode URLs.

Parameter	Description
`q`	Optional. A search query string. Organization tags are searchable by name likeness.
`filter[exclude][taggable][id]`	Optional. If specified, omits organization's related workspace's tags.
`page[number]`	Optional. If omitted, the endpoint will return the first page.
`page[size]`	Optional. If omitted, the endpoint will return 20 organization tags per page.

Sample Request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/organizations/hashicorp/tags

Sample Response

{
  "data": [
    {
      "id": "tag-1",
      "type": "tags",
      "attributes": {
        "name": "tag1",
        "created-at":  "2022-03-09T06:04:39.585Z",
        "instance-count": 1
      },
      "relationships": {
        "organization": {
          "data": {
            "id": "my-organization",
            "type": "organizations"
          }
        }
      }
    },
    {
      "id": "tag-2",
      "type": "tags",
      "attributes": {
        "name": "tag2",
        "created-at":  "2022-03-09T06:04:39.585Z",
        "instance-count": 2
      },
      "relationships": {
        "organization": {
          "data": {
            "id": "my-organization",
            "type": "organizations"
          }
        }
      }
    }
  ]
}

Delete tags

This endpoint deletes one or more tags from an organization. The organization and tags must already exist. Tags deleted here will be removed from all other resources.

DELETE /organizations/:organization_name/tags

Parameter	Description
`:organization_name`	The name of the organization to delete tags from

Status	Response	Reason(s)
204	No Content	Successfully removed tags from organization
404	JSON API error object	Organization not found, or user unauthorized to perform action

Request Body

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

It is important to note that type and id are required.

Key path	Type	Default	Description
`data[].type`	string		Must be `"tags"`.
`data[].id`	string		The id of the tag to remove.

Sample Payload

{
  "data": [
    {
      "type": "tags",
      "id": "tag-Yfha4YpPievQ8wJw"
    }
  ]
}

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request DELETE \
  --data @payload.json \
  https://app.terraform.io/api/v2/organizations/hashicorp/tags

Sample Response

No response body.

Status code 204.

Add workspaces to a tag

POST /tags/:tag_id/relationships/workspaces

Parameter	Description
`:tag_id`	The ID of the tag that workspaces should have added.

Status	Response	Reason(s)
204	No Content	Successfully added workspaces to tag
404	JSON API error object	Tag not found, or user unauthorized to perform action

Request Body

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

Key path	Type	Default	Description
`data[].type`	string		Must be `"workspaces"`.
`data[].id`	string		The id of the workspace to add.

Sample Request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/tags/tag-2/relationships/workspaces

Sample Payload

{
  "data": [
      {
          "type": "workspaces",
          "id": "ws-pmKTbUwH2VPiiTC4"
      }
  ]
}

Sample Response

No response body.

Status code 204.

Tag bindings

Tag bindings capture the direct association between a project tag and a taggable resource, such as a registry artifact. HCP Terraform creates a tag binding when you assign a project tag to a resource and removes the binding when you unassign the tag.

The following types of project tags can create tag bindings:

Reserved keys: Tags with a system-reserved key. Refer to the reserved tag keys API reference for more information.
Standard key/value tags: User-defined tags in the form of key/value pairs.
Key-only tags: Tags that consist of a key without an associated value.

The following endpoint retrieves all tag bindings within an organization. The response includes its attributes, including values for their key and value attributes.

GET /organizations/:organization_name/tag-bindings

Parameter	Description
`:organization_name`	The name of the organization to list tag bindings from.

Sample request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/organizations/hashicorp/tag-bindings

Sample response

{
    "data": [
        {
            "id": "tb-NZAkmndfdJvuo2pD",
            "type": "tag-bindings",
            "attributes": {
                "key": "Environment",
                "value": "Prod",
                "created-at": "2026-07-14T11:57:54.121Z"
            }
        },
        {
            "id": "tb-CyflkdskJFcQ",
            "type": "tag-bindings",
            "attributes": {
                "key": "Dept",
                "value": "Eng",
                "created-at": "2026-07-14T11:57:54.144Z"
            }
        },
        {
            "id": "tb-edfFklkFsdfB4YDp",
            "type": "tag-bindings",
            "attributes": {
                "key": "TestTag",
                "value": "",
                "created-at": "2026-07-14T11:57:54.155Z"
            }
        },
        {
            "id": "tb-bdsklmfe23FN524z",
            "type": "tag-bindings",
            "attributes": {
                "key": "Environment",
                "value": "Prod",
                "created-at": "2026-07-14T12:58:48.277Z"
            }
        },
        {
            "id": "tb-Ur398fdjkmsakfSSR",
            "type": "tag-bindings",
            "attributes": {
                "key": "Environment",
                "value": "Prod",
                "created-at": "2026-07-14T12:58:48.288Z"
            }
        }
    ],
    "links": {
        "self": "https://app.terraform.io/api/organizations/my-organization/tag-bindings?page%5Bnumber%5D=1&page%5Bsize%5D=20",
        "first": "https://app.terraform.io/api/organizations/my-organization/tag-bindings?page%5Bnumber%5D=1&page%5Bsize%5D=20",
        "prev": null,
        "next": null,
        "last": "https://app.terraform.io/api/organizations/my-organization/tag-bindings?page%5Bnumber%5D=1&page%5Bsize%5D=20"
    },
    "meta": {
        "pagination": {
            "current-page": 1,
            "page-size": 20,
            "prev-page": null,
            "next-page": null,
            "total-pages": 1,
            "total-count": 5
        }
    }
}

Query parameters

This endpoint supports pagination with standard URL query parameters.

Parameter	Description
`filter[taggable-type]`	Optional. Filters tag bindings by the type of resource they are bound to. Supports `projects`.
`filter[tagged][INDEX][key]`	Optional. Filters tag bindings by tag key.
`filter[tagged][INDEX][value]`	Optional. Filters tag bindings by tag value.
`fields[tag-binding]`	Optional. A comma-separated list of fields to include in the response, such as `counts`, `key`, `value`, `target`, and `created_at`.
`page[number]`	Optional. If omitted, the endpoint returns the first page.
`page[size]`	Optional. If omitted, the endpoint returns 20 tag bindings per page.

When you provide multiple filter[tagged] conditions, the INDEX value determines how HCP Terraform combines them:

Use the same index to combine a key and value with AND. For example, filter[tagged][0][key]=environment&filter[tagged][0][value]=prod matches tags where the key is environment and the value is prod.
Use different indexes to combine conditions with OR. For example, filter[tagged][0][key]=environment&filter[tagged][1][value]=prod matches tags where the key is environment or the value is prod.

Sample request with query parameters

The following request filters project tag bindings where the key is Environment and the value is Prod, and it limits the response fields to counts, key, value, and target.

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  "https://app.terraform.io/api/organizations/my-organization/tag-bindings?filter[tagged][0][key]=Environment&filter[tagged][1][value]=Prod?page[size]=2&fields[tag-binding]=counts,key,value,target"

Sample response with query parameters

{
  "data": [
    {
      "id": "tb-NZAtJZuE6svuo2pD",
      "type": "tag-bindings",
      "attributes": {
        "key": "Environment",
        "value": "Prod",
        "counts": {
          "workspaces": 2,
          "projects": 1
        }
      },
      "relationships": {
        "target": {
          "data": {
            "id": "prj-1inGKQeg6hft6poy",
            "type": "projects"
          },
          "links": {
            "self": "/api/v2/projects/prj-1inGKQeg6hft6poy"
          }
        }
      }
    },
    {
      "id": "tb-bH9RM2x6SmFN524z",
      "type": "tag-bindings",
      "attributes": {
        "key": "Environment",
        "value": "Prod",
        "counts": {
          "workspaces": 0,
          "projects": 0
        }
      },
      "relationships": {
        "target": {
          "data": {
            "id": "mod-7Ecnpevu8A6TGnhB",
            "type": "registry-modules"
          },
          "links": {
            "self": "/api/v2/organizations/HC_Prod_Carolina/registry-modules/private/HC_Prod_Carolina/s3-bucket/aws"
          }
        }
      }
    },
    {
      "id": "tb-Ur3KXeWyA7KefSSR",
      "type": "tag-bindings",
      "attributes": {
        "key": "Environment",
        "value": "Prod",
        "counts": {
          "workspaces": 0,
          "projects": 0
        }
      },
      "relationships": {
        "target": {
          "data": {
            "id": "mod-ntUw7VH1a2WNNoMy",
            "type": "registry-modules"
          },
          "links": {
            "self": "/api/v2/organizations/HC_Prod_Carolina/registry-modules/private/HC_Prod_Carolina/petstore/blueprint"
          }
        }
      }
    }
  ],
  "links": {
    "self": "https://app.terraform.io/api/organizations/HC_Prod_Carolina/tag-bindings?fields%5Btag-binding%5D=counts%2Ckey%2Cvalue%2Ctarget\u0026filter%5Btagged%5D%5B0%5D%5Bkey%5D=Environment\u0026filter%5Btagged%5D%5B1%5D%5Bvalue%5D=Prod%3Fpage%5Bsize%5D%3D2\u0026page%5Bnumber%5D=1\u0026page%5Bsize%5D=20",
    "first": "https://app.terraform.io/api/organizations/HC_Prod_Carolina/tag-bindings?fields%5Btag-binding%5D=counts%2Ckey%2Cvalue%2Ctarget\u0026filter%5Btagged%5D%5B0%5D%5Bkey%5D=Environment\u0026filter%5Btagged%5D%5B1%5D%5Bvalue%5D=Prod%3Fpage%5Bsize%5D%3D2\u0026page%5Bnumber%5D=1\u0026page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "https://app.terraform.io/api/organizations/HC_Prod_Carolina/tag-bindings?fields%5Btag-binding%5D=counts%2Ckey%2Cvalue%2Ctarget\u0026filter%5Btagged%5D%5B0%5D%5Bkey%5D=Environment\u0026filter%5Btagged%5D%5B1%5D%5Bvalue%5D=Prod%3Fpage%5Bsize%5D%3D2\u0026page%5Bnumber%5D=1\u0026page%5Bsize%5D=20"
  },
  "meta": {
    "pagination": {
      "current-page": 1,
      "page-size": 20,
      "prev-page": null,
      "next-page": null,
      "total-pages": 1,
      "total-count": 3
    }
  }
}

Organization tags API reference

List Tags

Query Parameters

Sample Request

Sample Response

Delete tags

Request Body

Sample Payload

Sample Request

Sample Response

Add workspaces to a tag

Request Body

Sample Request

Sample Payload

Sample Response

Tag bindings

List tag bindings

Sample request

Sample response

Query parameters

Sample request with query parameters

Sample response with query parameters