Reserved tag keys API reference

Use the /reserved-tag-keys API endpoints to define and manage tag keys that have special meaning for your organization. Reserving tag keys enable project and workspace managers to follow a consistent tagging strategy across the organization. You can also use them to provide project managers with a means of disabling overrides for inherited tags.

The following table describes the available endpoints:

Method	Path	Description
`GET`	`/organizations/:organization_name/reserved-tag-keys`	List reserved tag keys for the specified organization.
`POST`	`/organizations/:organization_name/reserved-tag-keys`	Add a reserved tag key to the specified organization.
`PATCH`	`/reserved-tags/:reserved_tag_key_id`	Update a reserved tag key with the specified ID.
`DELETE`	`/reserved-tags/:reserved_tag_key_id`	Delete a reserved tag key with the specified ID.

Path parameters

The /reserved-tag-keys/ API endpoints require the following path parameters:

Parameter	Description
`:reserved_tag_key_id`	The external ID of the reserved tag key.
`:organization_name`	The name of the organization containing the reserved tags.

List reserved tag keys

GET /organizations/:organization_name/reserved-tag-keys

Sample payload

This endpoint does not require a payload.

Sample request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://app.terraform.io/api/v2/organizations/my-organization/reserved-tag-keys

Sample response

{
    "data": [
        {
            "id": "rtk-jjnTseo8NN1jACbk",
            "type": "reserved-tag-keys",
            "attributes": {
                "key": "environment",
                "disable-overrides": false,
                "created-at": "2024-08-13T23:06:42.523Z",
                "updated-at": "2024-08-13T23:06:42.523Z"
            }
        },
        {
            "id": "rtk-F1s7kKUShAQxhA1b",
            "type": "reserved-tag-keys",
            "attributes": {
                "key": "cost-center",
                "disable-overrides": false,
                "created-at": "2024-08-13T23:06:51.445Z",
                "updated-at": "2024-08-13T23:06:51.445Z"
            }
        },
    ],
    "links": {
        "self": "https://app.terraform.io/api/v2/organizations/my-organization/reserved-tag-keys?page%5Bnumber%5D=1&page%5Bsize%5D=20",
        "first": "https://app.terraform.io/api/v2/organizations/my-organization/reserved-tag-keys?page%5Bnumber%5D=1&page%5Bsize%5D=20",
        "prev": null,
        "next": null,
        "last": "https://app.terraform.io/api/v2/organizations/my-organization/reserved-tag-keys?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": 2
        }
    }
}

Create a reserved tag key

POST /organizations/:organization_name/reserved-tag-keys

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

Properties without a default value are required.

Key path	Type	Default	Description
`data.type`	string	none	Must be `reserved-tag-keys`.
`data.attributes.key`	string	none	The key targeted by this reserved
tag key.
`data.attributes.disable-overrides`	boolean	none	If `true`, disables
overriding inherited tags with the specified key at the workspace level.

Sample payload

{
  "data": {
    "type": "reserved-tag-keys",
    "attributes": {
      "key": "environment",
      "disable-overrides": false
    }
  }
}

Sample request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  https://app.terraform.io/api/v2/organizations/${ORGANIZATION_NAME}/reserved-tag-keys

Sample response

{
    "data": {
        "id": "rtk-Tj86UdGahKGDiYXY",
        "type": "reserved-tag-keys",
        "attributes": {
            "key": "environment",
            "disable-overrides": false,
            "created-at": "2024-09-04T05:02:06.794Z",
            "updated-at": "2024-09-04T05:02:06.794Z"
        }
    }
}

Update a reserved tag key

PATCH /reserved-tags/:reserved_tag_key_id

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

Properties without a default value are required.

Key path	Type	Default	Description
`data.type`	string	none	Must be `reserved-tag-keys`.
`data.attributes.key`	string	none	The key targeted by this reserved
tag key.
`data.attributes.disable-overrides`	boolean	none	If `true`, disables
overriding inherited tags with the specified key at the workspace level.

Sample payload

{
  "data": {
    "id": "rtk-Tj86UdGahKGDiYXY",
    "type": "reserved-tag-keys",
    "attributes": {
      "key": "env",
      "disable-overrides": true,
      "created-at": "2024-09-04T05:02:06.794Z",
      "updated-at": "2024-09-04T05:02:06.794Z"
    }
  }
}

Sample request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request PATCH \
  https://app.terraform.io/api/v2/reserved-tags/${RESERVED_TAG_ID}

Sample response

{
    "data": {
        "id": "rtk-zMtWLDftAjY3b5pA",
        "type": "reserved-tag-keys",
        "attributes": {
            "key": "env",
            "disable-overrides": true,
            "created-at": "2024-09-04T05:05:10.449Z",
            "updated-at": "2024-09-04T05:05:13.486Z"
        }
    }
}

Delete a reserved tag key

DELETE /reserved-tags/:reserved_tag_key_id

Sample payload

This endpoint does not require a payload.

Sample request

$ curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request DELETE \
  https://app.terraform.io/api/v2/reserved-tags/rtk-zMtWLDftAjY3b5pA

Sample response

This endpoint does not return a response body.