Terraform
Run Tasks API
Run tasks allow HCP Terraform to interact with external systems at specific points in the HCP Terraform run lifecycle. Run tasks are reusable configurations that you can associate to any workspace in an organization. This page lists the API endpoints for run tasks in an organization and explains how to associate run tasks to workspaces.
Note: HCP Terraform Free Edition includes one run task integration that you can apply to up to ten workspaces. Refer to HCP Terraform pricing for details.
Refer to run tasks Integration for the API endpoints related triggering run tasks and the expected integration response.
Required Permissions
To interact with run tasks on an organization, you need the Manage Run Tasks permission. To associate or dissociate run tasks in a workspace, you need the Manage Workspace Run Tasks permission on that particular workspace.
Create a Run Task
POST /organizations/:organization_name/tasks
Parameter | Description |
---|---|
:organization_name | The organization to create a run task in. The organization must already exist in HCP Terraform, and the token authenticating the API request must have owner permission. |
Status | Response | Reason |
---|---|---|
201 | JSON API document (type: "tasks" ) | Successfully created a run task |
404 | JSON API error object | Organization not found, or user unauthorized to perform action |
422 | JSON API error object | Malformed request body (missing attributes, wrong types, etc.) |
Request Body
This POST endpoint requires a JSON object with the following properties as a request payload.
Properties without a default value are required unless otherwise specified.
Key path | Type | Default | Description |
---|---|---|---|
data.type | string | Must be "tasks" . | |
data.attributes.name | string | The name of the task. Can include letters, numbers, - , and _ . | |
data.attributes.url | string | URL to send a run task payload. | |
data.attributes.description | string | The description of the run task. Can be up to 300 characters long including spaces, letters, numbers, and special characters. | |
data.attributes.category | string | Must be "task" . | |
data.attributes.hmac-key | string | (Optional) HMAC key to verify run task. | |
data.attributes.enabled | bool | true | (Optional) Whether the task will be run. |
data.attributes.global-configuration.enabled | bool | false | (Optional) Whether the task will be associated on all workspaces. |
data.attributes.global-configuration.stages | array | (Optional) An array of strings representing the stages of the run lifecycle when the run task should begin. Must be one or more of "pre_plan" , "post_plan" , "pre_apply" , or "post_apply" . | |
data.attributes.global-configuration.enforcement-level | string | (Optional) The enforcement level of the workspace task. Must be "advisory" or "mandatory" . |
Sample Payload
{
"data": {
"type": "tasks",
"attributes": {
"name": "example",
"url": "http://example.com",
"description": "Simple description",
"hmac_key": "secret",
"enabled": "true",
"category": "task",
"global-configuration": {
"enabled": true,
"stages": ["pre_plan"],
"enforcement-level": "mandatory"
}
}
}
}
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/my-organization/tasks
Sample Response
{
"data": {
"id": "task-7oD7doVTQdAFnMLV",
"type": "tasks",
"attributes": {
"category": "task",
"name": "my-run-task",
"url": "http://example.com",
"description": "Simple description",
"enabled": "true",
"hmac-key": null,
"global-configuration": {
"enabled": true,
"stages": ["pre_plan"],
"enforcement-level": "mandatory"
}
},
"relationships": {
"organization": {
"data": {
"id": "hashicorp",
"type": "organizations"
}
},
"tasks": {
"data": []
}
},
"links": {
"self": "/api/v2/tasks/task-7oD7doVTQdAFnMLV"
}
}
}
List Run Tasks
GET /organizations/:organization_name/tasks
Parameter | Description |
---|---|
:organization_name | The organization to list tasks for. |
Status | Response | Reason |
---|---|---|
200 | JSON API document (type: "tasks" ) | Request was successful |
404 | JSON API error object | Organization not found, or user unauthorized to perform action |
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 |
---|---|
include | Optional. Allows including related resource data. Value must be a comma-separated list containing one or more of workspace_tasks or workspace_tasks.workspace . |
page[number] | Optional. If omitted, the endpoint will return the first page. |
page[size] | Optional. If omitted, the endpoint will return 20 run tasks per page. |
Sample Request
curl \
--header "Authorization: Bearer $TOKEN" \
https://app.terraform.io/api/v2/organizations/my-organization/tasks
Sample Response
{
"data": [
{
"id": "task-7oD7doVTQdAFnMLV",
"type": "tasks",
"attributes": {
"category": "task",
"name": "my-task",
"url": "http://example.com",
"description": "Simple description",
"enabled": "true",
"hmac-key": null,
"global-configuration": {
"enabled": true,
"stages": ["pre_plan"],
"enforcement-level": "mandatory"
}
},
"relationships": {
"organization": {
"data": {
"id": "hashicorp",
"type": "organizations"
}
},
"tasks": {
"data": []
}
},
"links": {
"self": "/api/v2/tasks/task-7oD7doVTQdAFnMLV"
}
}
],
"links": {
"self": "https://app.terraform.io/api/v2/organizations/hashicorp/tasks?page%5Bnumber%5D=1&page%5Bsize%5D=20",
"first": "https://app.terraform.io/api/v2/organizations/hashicorp/tasks?page%5Bnumber%5D=1&page%5Bsize%5D=20",
"prev": null,
"next": null,
"last": "https://app.terraform.io/api/v2/organizations/hashicorp/tasks?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": 1
}
}
}
Show a Run Task
GET /tasks/:id
Parameter | Description |
---|---|
:id | The ID of the task to show. Use the "List Run Tasks" endpoint to find IDs. |
Status | Response | Reason |
---|---|---|
200 | JSON API document (type: "tasks" ) | The request was successful |
404 | JSON API error object | Run task not found or user unauthorized to perform action |
Parameter | Description |
---|---|
include | Optional. Allows including related resource data. Value must be a comma-separated list containing one or more of workspace_tasks or workspace_tasks.workspace . |
Sample Request
curl --request GET \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/vnd.api+json" \
https://app.terraform.io/api/v2/tasks/task-7oD7doVTQdAFnMLV
Sample Response
{
"data": {
"id": "task-7oD7doVTQdAFnMLV",
"type": "tasks",
"attributes": {
"category": "task",
"name": "my-task",
"url": "http://example.com",
"description": "Simple description",
"enabled": "true",
"hmac-key": null,
},
"relationships": {
"organization": {
"data": {
"id": "hashicorp",
"type": "organizations"
}
},
"tasks": {
"data": [
{
"id": "task-xjKZw9KaeXda61az",
"type": "tasks"
}
]
}
},
"links": {
"self": "/api/v2/tasks/task-7oD7doVTQdAFnMLV"
}
}
}
Update a Run Task
PATCH /tasks/:id
Parameter | Description |
---|---|
:id | The ID of the task to update. Use the "List Run Tasks" endpoint to find IDs. |
Status | Response | Reason |
---|---|---|
200 | JSON API document (type: "tasks" ) | The request was successful |
404 | JSON API error object | Run task not found or user unauthorized to perform action |
422 | JSON API error object | Malformed request body (missing attributes, wrong types, etc.) |
Request Body
This PATCH endpoint requires a JSON object with the following properties as a request payload.
Properties without a default value are required unless otherwise specified.
Key path | Type | Default | Description |
---|---|---|---|
data.type | string | Must be "tasks" . | |
data.attributes.name | string | (previous value) | The name of the run task. Can include letters, numbers, - , and _ . |
data.attributes.url | string | (previous value) | URL to send a run task payload. |
data.attributes.description | string | The description of the run task. Can be up to 300 characters long including spaces, letters, numbers, and special characters. | |
data.attributes.category | string | (previous value) | Must be "task" . |
data.attributes.hmac-key | string | (previous value) | (Optional) HMAC key to verify run task. |
data.attributes.enabled | bool | (previous value) | (Optional) Whether the task will be run. |
data.attributes.global-configuration.enabled | bool | (previous value) | (Optional) Whether the task will be associated on all workspaces. |
data.attributes.global-configuration.stages | array | (previous value) | (Optional) An array of strings representing the stages of the run lifecycle when the run task should begin. Must be one or more of "pre_plan" , "post_plan" , "pre_apply" , or "post_apply" . |
data.attributes.global-configuration.enforcement-level | string | (previous value) | (Optional) The enforcement level of the workspace task. Must be "advisory" or "mandatory" . |
Sample Payload
{
"data": {
"type": "tasks",
"attributes": {
"name": "new-example",
"url": "http://new-example.com",
"description": "New description",
"hmac_key": "new-secret",
"enabled": "false",
"category": "task",
"global-configuration": {
"enabled": false
}
}
}
}
Sample Request
curl \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/vnd.api+json" \
--request PATCH \
--data @payload.json \
https://app.terraform.io/api/v2/tasks/task-7oD7doVTQdAFnMLV
Sample Response
{
"data": {
"id": "task-7oD7doVTQdAFnMLV",
"type": "tasks",
"attributes": {
"category": "task",
"name": "new-example",
"url": "http://new-example.com",
"description": "New description",
"enabled": "false",
"hmac-key": null,
"global-configuration": {
"enabled": false,
"stages": ["pre_plan"],
"enforcement-level": "mandatory"
}
},
"relationships": {
"organization": {
"data": {
"id": "hashicorp",
"type": "organizations"
}
},
"tasks": {
"data": [
{
"id": "wstask-xjKZw9KaeXda61az",
"type": "workspace-tasks"
}
]
}
},
"links": {
"self": "/api/v2/tasks/task-7oD7doVTQdAFnMLV"
}
}
}
Delete a Run Task
DELETE /tasks/:id
Parameter | Description |
---|---|
:id | The ID of the run task to delete. Use the "List Run Tasks" endpoint to find IDs. |
Status | Response | Reason |
---|---|---|
204 | No Content | Successfully deleted the run task |
404 | JSON API error object | Run task not found, or user unauthorized to perform action |
Sample Request
curl \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/vnd.api+json" \
--request DELETE \
https://app.terraform.io/api/v2/tasks/task-7oD7doVTQdAFnMLV
Associate a Run Task to a Workspace
POST /workspaces/:workspace_id/tasks
Parameter | Description |
---|---|
:workspace_id | The ID of the workspace. |
This endpoint associates an existing run task to a specific workspace.
This involves setting the run task enforcement level, which determines whether the run task blocks runs from completing.
Advisory run tasks can not block a run from completing. If the task fails, the run will proceed with a warning.
Mandatory run tasks block a run from completing. If the task fails (including a timeout or unexpected remote error condition), the run stops with an error.
You may also configure the run task to begin during specific run stages. Run tasks use the Post-Plan Stage by default.
Status | Response | Reason |
---|---|---|
204 | No Content | The request was successful |
404 | JSON API error object | Workspace or run task not found or user unauthorized to perform action |
422 | JSON API error object | Malformed request body |
Request Body
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 | Must be "workspace-tasks" . | |
data.attributes.enforcement-level | string | The enforcement level of the workspace task. Must be "advisory" or "mandatory" . | |
data.attributes.stage | string | "post_plan" | DEPRECATED Use stages instead. The stage in the run lifecycle when the run task should begin. Must be "pre_plan" , "post_plan" , "pre_apply" , or "post_apply" . |
data.attributes.stages | array | ["post_plan"] | An array of strings representing the stages of the run lifecycle when the run task should begin. Must be one or more of "pre_plan" , "post_plan" , "pre_apply" , or "post_apply" . |
data.relationships.task.data.id | string | The ID of the run task. | |
data.relationships.task.data.type | string | Must be "tasks" . |
Sample Payload
{
"data": {
"type": "workspace-tasks",
"attributes": {
"enforcement-level": "advisory",
"stages": ["post_plan"]
},
"relationships": {
"task": {
"data": {
"id": "task-7oD7doVTQdAFnMLV",
"type": "tasks"
}
}
}
}
}
Sample Request
curl \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/vnd.api+json" \
--request POST \
--data @payload.json \
https://app.terraform.io/api/v2/workspaces/ws-PphL7ix3yGasYGrq/tasks
Sample Response
{
"data": {
"id": "wstask-tBXYu8GVAFBpcmPm",
"type": "workspace-tasks",
"attributes": {
"enforcement-level": "advisory",
"stage": "post_plan",
"stages": ["post_plan"]
},
"relationships": {
"task": {
"data": {
"id": "task-7oD7doVTQdAFnMLV",
"type": "tasks"
}
},
"workspace": {
"data": {
"id": "ws-PphL7ix3yGasYGrq",
"type": "workspaces"
}
}
},
"links": {
"self": "/api/v2/workspaces/ws-PphL7ix3yGasYGrq/tasks/task-tBXYu8GVAFBpcmPm"
}
}
}
List Workspace Run Tasks
GET /workspaces/:workspace_id/tasks
Parameter | Description |
---|---|
:workspace_id | The workspace to list tasks for. |
Status | Response | Reason |
---|---|---|
200 | JSON API document (type: "tasks" ) | Request was successful |
404 | JSON API error object | Workspace not found, or user unauthorized to perform action |
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 run tasks per page. |
Sample Request
curl \
--header "Authorization: Bearer $TOKEN" \
https://app.terraform.io/api/v2/workspaces/ws-kRsDRPtTmtcEme4t/tasks
Sample Response
{
"data": [
{
"id": "wstask-tBXYu8GVAFBpcmPm",
"type": "workspace-tasks",
"attributes": {
"enforcement-level": "advisory",
"stage": "post_plan",
"stages": ["post_plan"]
},
"relationships": {
"task": {
"data": {
"id": "task-hu74ST39g566Q4m5",
"type": "tasks"
}
},
"workspace": {
"data": {
"id": "ws-kRsDRPtTmtcEme4t",
"type": "workspaces"
}
}
},
"links": {
"self": "/api/v2/workspaces/ws-kRsDRPtTmtcEme4t/tasks/task-tBXYu8GVAFBpcmPm"
}
}
],
"links": {
"self": "https://app.terraform.io/api/v2/workspaces/ws-kRsDRPtTmtcEme4t/tasks?page%5Bnumber%5D=1&page%5Bsize%5D=20",
"first": "https://app.terraform.io/api/v2/workspaces/ws-kRsDRPtTmtcEme4t/tasks?page%5Bnumber%5D=1&page%5Bsize%5D=20",
"prev": null,
"next": null,
"last": "https://app.terraform.io/api/v2/workspaces/ws-kRsDRPtTmtcEme4t/tasks?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": 1
}
}
}
Show Workspace Run Task
GET /workspaces/:workspace_id/tasks/:id
Parameter | Description |
---|---|
:id | The ID of the workspace task to show. Use the "List Workspace Run Tasks" endpoint to find IDs. |
Status | Response | Reason |
---|---|---|
200 | JSON API document (type: "tasks" ) | The request was successful |
404 | JSON API error object | Workspace run task not found or user unauthorized to perform action |
Sample Request
curl --request GET \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/vnd.api+json" \
https://app.terraform.io/api/v2/workspaces/ws-kRsDRPtTmtcEme4t/tasks/wstask-tBXYu8GVAFBpcmPm
Sample Response
{
"data": {
"id": "wstask-tBXYu8GVAFBpcmPm",
"type": "workspace-tasks",
"attributes": {
"enforcement-level": "advisory",
"stage": "post_plan",
"stages": ["post_plan"]
},
"relationships": {
"task": {
"data": {
"id": "task-hu74ST39g566Q4m5",
"type": "tasks"
}
},
"workspace": {
"data": {
"id": "ws-kRsDRPtTmtcEme4t",
"type": "workspaces"
}
}
},
"links": {
"self": "/api/v2/workspaces/ws-kRsDRPtTmtcEme4t/tasks/wstask-tBXYu8GVAFBpcmPm"
}
}
}
Update Workspace Run Task
PATCH /workspaces/:workspace_id/tasks/:id
Parameter | Description |
---|---|
:id | The ID of the task to update. Use the "List Workspace Run Tasks" endpoint to find IDs. |
Status | Response | Reason |
---|---|---|
200 | JSON API document (type: "tasks" ) | The request was successful |
404 | JSON API error object | Workspace run task not found or user unauthorized to perform action |
422 | JSON API error object | Malformed request body (missing attributes, wrong types, etc.) |
Request Body
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 | (previous value) | Must be "workspace-tasks" . |
data.attributes.enforcement-level | string | (previous value) | The enforcement level of the workspace run task. Must be "advisory" or "mandatory" . |
data.attributes.stage | string | (previous value) | DEPRECATED Use stages instead. The stage in the run lifecycle when the run task should begin. Must be "pre_plan" or "post_plan" . |
data.attributes.stages | array | (previous value) | An array of strings representing the stages of the run lifecycle when the run task should begin. Must be one or more of "pre_plan" , "post_plan" , "pre_apply" , or "post_apply" . |
Sample Payload
{
"data": {
"type": "workspace-tasks",
"attributes": {
"enforcement-level": "mandatory",
"stages": ["post_plan"]
}
}
}
Deprecated Payload
{
"data": {
"type": "workspace-tasks",
"attributes": {
"enforcement-level": "mandatory",
"stages": ["post_plan"]
}
}
}
Sample Request
curl \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/vnd.api+json" \
--request PATCH \
--data @payload.json \
https://app.terraform.io/api/v2/workspaces/ws-kRsDRPtTmtcEme4t/tasks/wstask-tBXYu8GVAFBpcmPm
Sample Response
{
"data": {
"id": "wstask-tBXYu8GVAFBpcmPm",
"type": "workspace-tasks",
"attributes": {
"enforcement-level": "mandatory",
"stage": "post_plan",
"stages": ["post_plan"]
},
"relationships": {
"task": {
"data": {
"id": "task-hu74ST39g566Q4m5",
"type": "tasks"
}
},
"workspace": {
"data": {
"id": "ws-kRsDRPtTmtcEme4t",
"type": "workspaces"
}
}
},
"links": {
"self": "/api/v2/workspaces/ws-kRsDRPtTmtcEme4t/tasks/task-tBXYu8GVAFBpcmPm"
}
}
}
Delete Workspace Run Task
DELETE /workspaces/:workspace_id/tasks/:id
Parameter | Description |
---|---|
:id | The ID of the Workspace run task to delete. Use the "List Workspace Run Tasks" endpoint to find IDs. |
Status | Response | Reason |
---|---|---|
204 | No Content | Successfully deleted the workspace run task |
404 | JSON API error object | Workspace run task not found, or user unauthorized to perform action |
Sample Request
curl \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/vnd.api+json" \
--request DELETE \
https://app.terraform.io/api/v2/workspaces/ws-kRsDRPtTmtcEme4t/tasks/wstask-tBXYu8GVAFBpcmPm