Change requests API reference
Note
This feature is in beta. We recommend only using it non-production environments because updates during the beta phase may require you to destroy the explorer database. Running the explorer may increase the load on the Terraform Enterprise server in unexpected ways, resulting in slowdowns or outages.
Explorer on Terraform Enterprise only has access to data to the information available in the runs from Terraform Enterprise 1.0.0 and later.You can provide feedback on this feature by selectingGive Feedback from theActions menu or by contacting your account team.
You can use change requests to keep track of workspace to-dos directly on that workspace. Change requests are a backlog of the changes that a workspace requires, often to ensure that workspace keeps up with compliance and best practices of your company. Change requests can also triggerteam notifications to directly notify team members whenever someone creates a new change request.
List change requests
Use this endpoint to list a workspace's change requests.
GET api/v2/workspaces/:workspace_name/change-requests
| Parameter | Description |
|---|---|
:workspace_name | The name of workspace you want to list the change requests of. |
Query parameters
This endpoint supports paginationwith standard URL query parameters. Remember to percent-encode[ as%5B and] as%5D if your tooling doesn't automatically encode URLs.
| Parameter | Description |
|---|---|
page[number] | Optional. If omitted, the endpoint will return the first page. |
page[size] | Optional. If omitted, the endpoint will return 20 teams per page. |
Sample request
$ curl \ --header "Authorization: Bearer $TOKEN" \ --header "Content-Type: application/vnd.api+json" \ --request GET \ https://app.terraform.io/api/v2/workspaces/:workspace_name/change-requestsSample response
{ "data": [{ "type": "workspace_change_requests", "id": "wscr-yjLcKUMFTs6kr9iC" "attributes": { "subject": "[Action Required] Github Actions Pinning (SEC-090)", "message": "Some long description here", "archived-by": null, "archived-at": null, "created-at": "2024-06-12T21:45:11.594Z", "updated-at": "2024-06-12T21:45:11.594Z" }, "relationships": { "workspace" : { "data": { "id": "ws-FTs6kr9iCwweku", "type": "workspaces" } } } }, { "type": "workspace_change_requests", "id": "wscr-jXQMBkPAFGD6eyFs", "attributes": { "subject": "[Action Required] Github Actions Pinning (SEC-100)", "message": "Some long description here", "archived-by": null, "archived-at": null, "created-at": "2024-06-12T21:45:11.594Z", "updated-at": "2024-06-12T21:45:11.594Z" }, "relationships": { "workspace" : { "data": { "id": "ws-FTs6kr9iCwweku", "type": "workspaces" } } } }], "links": { "self": "https://localhost/api/v2/workspaces/example-workspace-name/change-requests?page%5Bnumber%5D=1\u0026page%5Bsize%5D=20", "first": "https://localhost/api/v2/workspaces/example-workspace-name/change-requests?page%5Bnumber%5D=1\u0026page%5Bsize%5D=20", "prev": null, "next": null, "last": "https://localhost/api/v2/workspaces/example-workspace-name/change-requests?page%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": 1 } }}Show a change request
Use this endpoint to list the details of a specific change request.
GET api/v2/workspaces/change-requests/:change_request_id
| Parameter | Description |
|---|---|
:change_request_id | The change request ID |
Sample request
$ curl \ --header "Authorization: Bearer $TOKEN" \ --header "Content-Type: application/vnd.api+json" \ --request GET \ https://app.terraform.io/api/v2/change-requests/wscr-jXQMBkPAFGD6eyFsSample response
{ "data": { "type": "workspace_change_requests", "id": "wscr-jXQMBkPAFGD6eyFs", "attributes": { "subject": "[Action Required] Github Actions Pinning (SEC-100)", "message": "Some long description here", "archived-by": null, "archived-at": null, "created-at": "2024-06-12T21:45:11.594Z", "updated-at": "2024-06-12T21:45:11.594Z" }, "relationships": { "workspace" : { "data": { "id": "ws-FTs6kr9iCwweku", "type": "workspaces" } } } }}Archive change request
If someone completes a change request, they can archive it to reflect the request's completion. You can still view archived change requests, however they are be sorted separated and marked as"archived".
POST api/v2/workspaces/change-requests/:change_request_id
| Parameter | Description |
|---|---|
:change_request_id | The ID of the change request to archive. |
Sample request
$ curl \ --header "Authorization: Bearer $TOKEN" \ --header "Content-Type: application/vnd.api+json" \ --request PATCH \ https://app.terraform.io/api/v2/workspaces/change-requests/wscr-jXQMBkPAFGD6eyFs`Sample response
{ "data": { "type": "workspace_change_requests", "id": "wscr-jXQMBkPAFGD6eyFs", "attributes": { "subject": "[Action Required] Github Actions Pinning (SEC-100)", "message": "Some long description here", "archived-by": "user-2n4yj45149kf", "archived-at": "2024-08-12T10:12:44.745Z", "created-at": "2024-06-12T21:45:11.594Z", "updated-at": "2024-06-12T21:45:11.594Z" }, "relationships": { "workspace" : { "data": { "id": "ws-FTs6kr9iCwweku", "type": "workspaces" } } } }}Create new change request
You can make change requests through theexplorer's experimental"bulk actions" endpoint.
POST /api/v2/organizations/:organization_name/explorer/bulk-actions
| Parameter | Description |
|---|---|
:organization_id | The ID of the organization you want to create a change request in. |
You must specify the following fields in your payload when creating a new change request.
| Key path | Type | Required | Description |
|---|---|---|---|
data.action_type | string | Required | The action to take. To create a change request, specify"change_request". |
data.action_inputs | object | Required | Arguments for the bulk action. |
data.action_inputs.subject | string | Required | The change request's subject line. |
data.action_inputs.message | string | Required | The change request's message, which HCP Terraform treats as markdown. |
data.target_ids | array | Optional | The IDs of the workspace you want to associate with this change request. You do not need to specify this field if you providedata.query. |
data.query | object | Optional | Anexplorer query with workspace data. You do not need to specify this field if you providedata.target_ids. |
Sample Payload
{ "data": { "type": "bulk_actions", "attributes": { "action_type": "change_requests", "action_inputs": { "subject": "[Action Required] Github Actions Pinning (SEC-090)", "message": "Some long description here", }, "query": { "type": "workspaces", "filter": [ "field":"workspace_name", "operator":"contains", "value": ["dev"] ] } },}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/organizations/:organization_name/explorer/bulk-actionsSample response
{ "data": { "id": "eba-3jk34n5k2bs", "attributes": { "organization_id": "org-9mvjfwpq098", "action_type": "change_requests", "action_inputs": { "subject": "[Action Required] Github Actions Pinning (SEC-090)", "message": "Some long description here", }, "created_by": { "id": "user-n86dcbcrwtw9", "type": "users" } }, "type": "explorer_bulk_actions", }}