» Run Triggers API

» 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-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

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=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

Parameter Description
:run_trigger_id The ID of the run trigger to show. Use the "List Run Triggers" endpoint to find IDs.
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-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

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

» 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

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.