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.