/tasks API reference for Terraform Enterprise | Terraform

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.

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"`.
`data.relationships.agent-pool.data.id`	string		(Optional) The agent pool that HCP Terraform uses to make requests for the run task. Requires the `private_run_tasks` feature entitlement and a self-hosted HCP Terraform agent with request forwarding.

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"
      }
    },
    "relationships": {
      "agent-pool": {
        "data": {
          "id": "apool-yoGUFz5zcRMMz53i",
          "type": "agent-pools"
        }
      }
    }
  }
}

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": []
      },
      "agent-pool": {
        "data": {
          "id": "apool-yoGUFz5zcRMMz53i",
          "type": "agent-pools"
        }
      }
    },
    "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

Run tasks API reference

Required Permissions

Create a Run Task

Request Body

Sample Payload

Sample Request

Sample Response

List Run Tasks

Query Parameters

Sample Request

Sample Response

Show a Run Task

Sample Request

Sample Response

Update a Run Task

Request Body

Sample Payload

Sample Request

Sample Response

Delete a Run Task

Sample Request

Associate a Run Task to a Workspace

Request Body

Sample Payload

Sample Request

Sample Response

List Workspace Run Tasks

Query Parameters

Sample Request

Sample Response

Show Workspace Run Task

Sample Request

Sample Response

Update Workspace Run Task

Request Body

Sample Payload

Deprecated Payload

Sample Request

Sample Response

Delete Workspace Run Task

Sample Request