Run triggers API reference
Create a Run Trigger
POST /workspaces/:workspace_id/run-triggers
| Parameter | Description |
|---|---|
:workspace_id | The ID of the workspace to create the run trigger in. Obtain this from the workspace settings or the Show Workspace endpoint. |
| Status | Response | Reason |
|---|---|---|
| 201 | JSON API document (type: "run-triggers") | Successfully created a run trigger |
| 404 | JSON API error object | Workspace or sourceable not found or user unauthorized to perform action |
| 422 | JSON API error object | Malformed 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 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" } } } }}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-triggersSample 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
| Parameter | Description |
|---|---|
:workspace_id | The ID of the workspace to list run triggers for. Obtain this from the workspace settings or the Show Workspace endpoint. |
| Status | Response | Reason |
|---|---|---|
| 200 | JSON API document (type: "run-triggers") | Request was successful |
| 400 | JSON API error object | Required parameter filter[run-trigger][type] is missing or has been given an invalid value |
| 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 |
|---|---|
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=inboundSample 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
| Parameter | Description |
|---|---|
:run_trigger_id | The 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. |
| Status | Response | Reason |
|---|---|---|
| 200 | JSON API document (type: "run-triggers") | The request was successful |
| 404 | JSON API error object | Run 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-3yVQZvHzf5j3WRJ1Sample 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
| Parameter | Description |
|---|---|
:run_trigger_id | The 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. |
| Status | Response | Reason |
|---|---|---|
| 204 | No Content | Successfully deleted the run trigger |
| 404 | JSON API error object | Run 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-3yVQZvHzf5j3WRJ1Available 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.
workspace- The full workspace object.sourceable- The full source workspace object.