Change requests API reference

Note: Change requests are in public beta. All APIs and workflows are subject to change.

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 trigger team notifications to directly notify team members whenever someone creates a new change request.

Note: Change requests are available in the HCP Terraform Plus Edition. Refer to HCP Terraform pricing for details.

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 pagination with 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-requests

Sample 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-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": 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 the explorer'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 provide `data.query`.
`data.query`	object	Optional	An explorer query with workspace data. You do not need to specify this field if you provide `data.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-actions

Sample 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",
  }
}