Tasks API reference

Tasks allow HCP Terraform workspaces to interact with external systems at specific points in the HCP Terraform run lifecycle. Tasks are reusable configurations that you can associate to any workspace in an organization. This page lists the API endpoints for tasks in an organization and explains how to associate 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 tasks Integration for the API endpoints related triggering tasks and the expected integration response.

Required permissions

To interact with tasks on an organization, you need the Manage Run Tasks permission. To associate or dissociate tasks in a workspace, you need the Manage Workspace Run Tasks permission on that particular workspace.

Create a task

POST /organizations/:organization_name/tasks

Parameter	Description
`:organization_name`	The organization to create a 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 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 task payload.
`data.attributes.description`	string		The description of the 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 task.
`data.attributes.enabled`	bool	true	(Optional) Whether the task will be run.
`data.attributes.global-configuration	object		(Optional) The global configuration object. Ignored if a `task-configs` relationship is present. If a `task-configs` relationship is not present, it will create a Task configuration owned by the organization.
`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 task. Requires HCP Terraform Premium plan, the `private_run_tasks` feature entitlement, and a self-hosted HCP Terraform agent with request forwarding.
`data.relationships.task-configs.data`	list of objects		(Optional) The task configurations for the task.
`data.relationships.task-configs.data.type`	string		Must be `"task-configs"`.
`data.relationships.task-configs.data.attributes.global`	string		Is this task configuration globally applied. See: Global vs Targeted Configurations
`data.relationships.task-configs.data.attributes.enforcement-level`	string		The enforcement level of the task configuration. Must be `"advisory"` or `"mandatory"`.
`data.relationships.task-configs.data.attributes.allowed-stages`	array		An array of strings representing the stages of the run lifecycle when the task should begin. Must be one or more of `"pre_plan"`, `"post_plan"`, `"pre_apply"`, or `"post_apply"`.
`data.relationships.task-configs.data.relationships.owner.data.id`	string		The owner id of the task configuration.
`data.relationships.task-configs.data.relationships.owner.data.type`	string		The owner type of the task configuration. See: Task Configuration Owners
`data.relationships.task-configs.data.relationships.projects.data`	list of objects		Specifies a list of projects to associated to the task configuration. See: Global vs Targeted Configurations
`data.relationships.task-configs.data.relationships.projects.data.type`	string		Must be `projects` for each object.
`data.relationships.task-configs.data.relationships.projects.data.id`	string		The id of the project to associate.

Sample payload

{
  "data": {
    "type": "tasks",
    "attributes": {
      "name": "example",
      "url": "http://example.com",
      "description": "Simple description",
      "hmac_key": "secret",
      "enabled": "true",
      "category": "task"
    },
    "relationships": {
      "agent-pool": {
        "data": {
          "id": "apool-yoGUFz5zcRMMz53i",
          "type": "agent-pools"
        }
      }
    }
  }
}

The following request includes a task configuration.

{
  "data": {
    "type": "tasks",
    "attributes": {
      "name": "example",
      "url": "http://example.com",
      "description": "Simple description",
      "hmac_key": "secret",
      "enabled": "true",
      "category": "task",
    },
    "relationships": {
      "agent-pool": {
        "data": {
          "id": "apool-yoGUFz5zcRMMz53i",
          "type": "agent-pools"
        }
      },
      "task-configs": {
        "data": [
          {
            "type": "task-configs",
            "attributes": {
              "global": true,
              "enforcement-level": "mandatory",
              "allowed-stages": [
                "pre_plan"
              ]
            },
            "relationships": {
              "owner": {
                "data": {
                  "id": "my-organization",
                  "type": "organizations"
                }
              }
            }
          }
        ]
      }
    }
  }
}

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

GET /tasks/:id

Parameter	Description
`:id`	The ID of the task to show. Use the "List Tasks" endpoint to find IDs.

Status	Response	Reason
200	JSON API document (`type: "tasks"`)	The request was successful
404	JSON API error object	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 tequest

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 task

PATCH /tasks/:id

Parameter	Description
`:id`	The ID of the task to update. Use the "List Tasks" endpoint to find IDs.

Status	Response	Reason
200	JSON API document (`type: "tasks"`)	The request was successful
404	JSON API error object	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 task. Can include letters, numbers, `-`, and `_`.
`data.attributes.url`	string	(previous value)	URL to send a task payload.
`data.attributes.description`	string		The description of the 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 task.
`data.attributes.enabled`	bool	(previous value)	(Optional) Whether the task will be run.
`data.attributes.global-configuration	object		(Optional) The global configuration object. If it is present, it will create or update a Task configuration owned by the organization.
`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": "new-example",
      "url": "http://new-example.com",
      "description": "New description",
      "hmac_key": "new-secret",
      "enabled": "false",
      "category": "task"
    }
  }
}

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
      },
      "relationships": {
        "organization": {
          "data": {
            "id": "hashicorp",
            "type": "organizations"
          }
        },
        "tasks": {
          "data": [
          {
            "id": "wstask-xjKZw9KaeXda61az",
            "type": "workspace-tasks"
          }
          ]
        }
      },
      "links": {
        "self": "/api/v2/tasks/task-7oD7doVTQdAFnMLV"
      }
  }
}

Delete a task

DELETE /tasks/:id

Parameter	Description
`:id`	The ID of the task to delete. Use the "List Tasks" endpoint to find IDs.

Status	Response	Reason
204	No Content	Successfully deleted the task
404	JSON API error object	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 Task to a Workspace

POST /workspaces/:workspace_id/tasks

Parameter	Description
`:workspace_id`	The ID of the workspace.

This endpoint associates an existing task to a specific workspace.

This involves setting the task enforcement level, which determines whether the task blocks runs from completing.

Advisory tasks cannot block a run from completing. If the task fails, the run will proceed with a warning.
Mandatory 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 task to begin during specific run stages. 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 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 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 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 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 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 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 task

GET /workspaces/:workspace_id/tasks/:id

Parameter	Description
`:id`	The ID of the workspace task to show. Use the "List Workspace Tasks" endpoint to find IDs.

Status	Response	Reason
200	JSON API document (`type: "tasks"`)	The request was successful
404	JSON API error object	Workspace 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 task

PATCH /workspaces/:workspace_id/tasks/:id

Parameter	Description
`:id`	The ID of the task to update. Use the "List Workspace Tasks" endpoint to find IDs.

Status	Response	Reason
200	JSON API document (`type: "tasks"`)	The request was successful
404	JSON API error object	Workspace 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 task. Must be `"advisory"` or `"mandatory"`.
`data.attributes.stage`	string	(previous value)	DEPRECATED Use `stages` instead. The stage in the run lifecycle when the 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 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"]
      }
  }
}

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 task

DELETE /workspaces/:workspace_id/tasks/:id

Parameter	Description
`:id`	The ID of the Workspace task to delete. Use the "List Workspace Tasks" endpoint to find IDs.

Status	Response	Reason
204	No Content	Successfully deleted the workspace task
404	JSON API error object	Workspace 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