A new platform for documentation and tutorials is launching soon.
We are migrating Terraform documentation into HashiCorp Developer, our new developer experience.
Search Terraform documentation » Run Triggers API» Create a Run TriggerPOST /workspaces/:workspace_id/run-triggers
» PermissionsIn 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 BodyThis 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.relationships.sourceable.data
object A 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"
}
}
}
}
}
{
"data" : {
"relationships" : {
"sourceable" : {
"data" : {
"id" : "ws-2HRvNs49EWPjDqT1" ,
"type" : "workspaces"
}
}
}
}
}
» Sample Requestcurl \
--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
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"
}
}
}
{
"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 TriggersGET /workspaces/:workspace_id/run-triggers
» Query ParametersThis 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 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.
» PermissionsIn order to list run triggers, the user must have permission to read runs for the specified workspace. (More about permissions. )
» Sample Requestcurl \
--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
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
}
}
}
{
"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 TriggerGET /run-triggers/:run_trigger_id
Parameter Description :run_trigger_id
The ID of the run trigger to show. Use the "List Run Triggers" endpoint to find IDs.
» PermissionsIn 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 Requestcurl \
--request GET \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
https://app.terraform.io/api/v2/run-triggers/rt-3yVQZvHzf5j3WRJ1
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"
}
}
}
{
"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 TriggerDELETE /run-triggers/:run_trigger_id
Parameter Description :run_trigger_id
The ID of the run trigger to delete. Use the "List Run Triggers" endpoint to find IDs.
Status Response Reason 204 Nothing Successfully deleted the run trigger 404 JSON API error object Run trigger not found or user unauthorized to perform action
» PermissionsIn order to delete a run trigger, the user must have admin access to the specified workspace. (More about permissions. )
» Sample Requestcurl \
--request DELETE \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
https://app.terraform.io/api/v2/run-triggers/rt-3yVQZvHzf5j3WRJ1
curl \
--request DELETE \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
https://app.terraform.io/api/v2/run-triggers/rt-3yVQZvHzf5j3WRJ1
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.