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.

List Tags

GET /organizations/:organization_name/tags

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.

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

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.

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

Request Body

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

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.