Organization Tags API

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

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.