HashiConf 2025 Don't miss the live stream of HashiConf Day 2 happening now View live stream
Terraform
Terraform Home

Run triggers API reference

You can establish connections between one or more workspaces in your organization and use the run-triggers endpoint to allow HCP Terraform to automatically queue runs in your workspace when a successful run apply operation is performed in any of the source workspaces. You can connect each workspace to up to 20 source workspaces.

Create a Run Trigger

POST /workspaces/:workspace_id/run-triggers

ParameterDescription
:workspace_idThe ID of the workspace to create the run trigger in. Obtain this from the workspace settings or the Show Workspace endpoint.
StatusResponseReason
201JSON API document (type: "run-triggers")Successfully created a run trigger
404JSON API error objectWorkspace or sourceable not found or user unauthorized to perform action
422JSON API error objectMalformed request body (missing attributes, wrong types, etc.)

Permissions

In order to create a run trigger, the user must have admin access to the specified workspace and permission to read runs for the sourceable workspace. (More about permissions.)

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 pathTypeDefaultDescription
data.relationships.sourceable.dataobjectA JSON API relationship object that represents the source workspace for the run trigger. This object must have id and type properties, and the type property must be workspaces (e.g. { "id": "ws-2HRvNs49EWPjDqT1", "type": "workspaces" }). Obtain workspace IDs from the workspace settings or the Show Workspace endpoint.

Sample Payload

{  "data": {  "relationships": {  "sourceable": {  "data": {  "id": "ws-2HRvNs49EWPjDqT1",  "type": "workspaces"  }  }  }  } }

Sample Request

curl \  --request POST \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  --data @payload.json \  https://app.terraform.io/api/v2/workspaces/ws-XdeUVMWShTesDMME/run-triggers

Sample Response

{  "data": {  "id": "rt-3yVQZvHzf5j3WRJ1",  "type": "run-triggers",  "attributes": {  "workspace-name": "workspace-1",  "sourceable-name": "workspace-2",  "created-at": "2018-09-11T18:21:21.784Z"  },  "relationships": {  "workspace": {  "data": {  "id": "ws-XdeUVMWShTesDMME",  "type": "workspaces"  }  },  "sourceable": {  "data": {  "id": "ws-2HRvNs49EWPjDqT1",  "type": "workspaces"  }  }  },  "links": {  "self": "/api/v2/run-triggers/rt-3yVQZvHzf5j3WRJ1"  }  } }

List Run Triggers

GET /workspaces/:workspace_id/run-triggers

ParameterDescription
:workspace_idThe ID of the workspace to list run triggers for. Obtain this from the workspace settings or the Show Workspace endpoint.
StatusResponseReason
200JSON API document (type: "run-triggers")Request was successful
400JSON API error objectRequired parameter filter[run-trigger][type] is missing or has been given an invalid value
404JSON API error objectWorkspace 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.

ParameterDescription
filter[run-trigger][type]Required Which type of run triggers to list; valid values are inbound or outbound. inbound run triggers create runs in the specified workspace, and outbound run triggers create runs in other workspaces.
page[number]Optional. If omitted, the endpoint will return the first page.
page[size]Optional. If omitted, the endpoint will return 20 run triggers per page.

Permissions

In order to list run triggers, the user must have permission to read runs for the specified workspace. (More about permissions.)

Sample Request

curl \  --request GET \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  https://app.terraform.io/api/v2/workspaces/ws-XdeUVMWShTesDMME/run-triggers?filter%5Brun-trigger%5D%5Btype%5D=inbound

Sample Response

{  "data": [  {  "id": "rt-WygcwSBuYaQWrM39",  "type": "run-triggers",  "attributes": {  "workspace-name": "workspace-1",  "sourceable-name": "workspace-2",  "created-at": "2018-09-11T18:21:21.784Z"  },  "relationships": {  "workspace": {  "data": {  "id": "ws-XdeUVMWShTesDMME",  "type": "workspaces"  }  },  "sourceable": {  "data": {  "id": "ws-2HRvNs49EWPjDqT1",  "type": "workspaces"  }  }  },  "links": {  "self": "/api/v2/run-triggers/rt-WygcwSBuYaQWrM39"  }  },  {  "id": "rt-8F5JFydVYAmtTjET",  "type": "run-triggers",  "attributes": {  "workspace-name": "workspace-1",  "sourceable-name": "workspace-3",  "created-at": "2018-09-11T18:21:21.784Z"  },  "relationships": {  "workspace": {  "data": {  "id": "ws-XdeUVMWShTesDMME",  "type": "workspaces"  }  },  "sourceable": {  "data": {  "id": "ws-BUHBEM97xboT8TVz",  "type": "workspaces"  }  }  },  "links": {  "self": "/api/v2/run-triggers/rt-8F5JFydVYAmtTjET"  }  }  ],  "links": {  "self": "https://app.terraform.io/api/v2/workspaces/ws-xdiJLyGpCugbFDE1/run-triggers?filter%5Brun-trigger%5D%5Btype%5D=inbound&page%5Bnumber%5D=1&page%5Bsize%5D=20",  "first": "https://app.terraform.io/api/v2/workspaces/ws-xdiJLyGpCugbFDE1/run-triggers?filter%5Brun-trigger%5D%5Btype%5D=inbound&page%5Bnumber%5D=1&page%5Bsize%5D=20",  "prev": null,  "next": null,  "last": "https://app.terraform.io/api/v2/workspaces/ws-xdiJLyGpCugbFDE1/run-triggers?filter%5Brun-trigger%5D%5Btype%5D=inbound&page%5Bnumber%5D=1&page%5Bsize%5D=20"  },  "meta": {  "pagination": {  "current-page": 1,  "prev-page": null,  "next-page": null,  "total-pages": 1,  "total-count": 2  }  } }

Show a Run Trigger

GET /run-triggers/:run_trigger_id

ParameterDescription
:run_trigger_idThe ID of the run trigger to show. Send a GET request to the run-triggers endpoint to find IDs. Refer to List Run Triggers for details.
StatusResponseReason
200JSON API document (type: "run-triggers")The request was successful
404JSON API error objectRun trigger not found or user unauthorized to perform action

Permissions

In order to show a run trigger, the user must have permission to read runs for either the workspace or sourceable workspace of the specified run trigger. (More about permissions.)

Sample Request

curl \  --request GET \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  https://app.terraform.io/api/v2/run-triggers/rt-3yVQZvHzf5j3WRJ1

Sample Response

{  "data": {  "id": "rt-3yVQZvHzf5j3WRJ1",  "type": "run-triggers",  "attributes": {  "workspace-name": "workspace-1",  "sourceable-name": "workspace-2",  "created-at": "2018-09-11T18:21:21.784Z"  },  "relationships": {  "workspace": {  "data": {  "id": "ws-XdeUVMWShTesDMME",  "type": "workspaces"  }  },  "sourceable": {  "data": {  "id": "ws-2HRvNs49EWPjDqT1",  "type": "workspaces"  }  }  },  "links": {  "self": "/api/v2/run-triggers/rt-3yVQZvHzf5j3WRJ1"  }  } }

Delete a Run Trigger

DELETE /run-triggers/:run_trigger_id

ParameterDescription
:run_trigger_idThe ID of the run trigger to delete. Send a GET request to the run-triggers endpoint o find IDs. Refer to List Run Triggers for details.
StatusResponseReason
204No ContentSuccessfully deleted the run trigger
404JSON API error objectRun trigger not found or user unauthorized to perform action

Permissions

In order to delete a run trigger, the user must have admin access to the specified workspace. (More about permissions.)

Sample Request

curl \  --request DELETE \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  https://app.terraform.io/api/v2/run-triggers/rt-3yVQZvHzf5j3WRJ1

Available Related Resources

The GET endpoints above can optionally return related resources, if requested with the include query parameter. The following resource types are available:

These includes respect read permissions. If you do not have access to read the related resource, it will not be returned.

Edit this page on GitHub