Terraform
Admin Workspaces API
Terraform Enterprise Only: The admin API is exclusive to Terraform Enterprise, and can only be used by the admins and operators who install and maintain their organization's Terraform Enterprise instance.
The Workspaces Admin API contains endpoints to help site administrators manage workspaces.
List all workspaces
GET /api/v2/admin/workspaces
This endpoint lists all workspaces in the Terraform Enterprise installation.
| Status | Response | Reason |
|---|---|---|
| 200 | JSON API document (type: "workspaces") | Successfully listed workspaces |
| 404 | JSON API error object | Client is not an administrator. |
Query Parameters
These are standard URL query parameters. Remember to percent-encode [ as %5B and ] as %5D if your tooling doesn't automatically encode URLs.
| Parameter | Description |
|---|---|
q | Optional. A search query string. Workspaces are searchable by name and organization name. |
filter[current_run][status] | Optional. A comma-separated list of Run statuses to restrict results to, which can include any of the following: "pending", "plan_queued", "planning", "planned", "confirmed", "apply_queued", "applying", "applied", "discarded", "errored", "canceled", "cost_estimating", "cost_estimated", "policy_checking", "policy_override", "policy_soft_failed", "policy_checked", and "planned_and_finished". |
sort | Optional. Allows sorting the organization's workspaces by a provided value. You can sort by "name", "current-run.created-at" (the time of the current run), and "latest-change-at" (the creation time of the latest state version or the workspace itself if no state version exists). Prepending a hyphen to the sort parameter reverses the order. For example, "-name" sorts by name in reverse alphabetical order. If omitted, the default sort order is arbitrary but stable. |
page[number] | Optional. If omitted, the endpoint will return the first page. |
page[size] | Optional. If omitted, the endpoint will return 20 workspaces per page. |
Available Related Resources
This GET endpoint can optionally return related resources, if requested with the include query parameter. The following resource types are available:
| Resource Name | Description |
|---|---|
organization | The organization for each returned workspace. |
organization.owners | A list of owners for each workspace's associated organization. |
current_run | The current run for each returned workspace. |
Sample Request
curl \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/vnd.api+json" \
"https://app.terraform.io/api/v2/admin/workspaces"
Sample Response
{
"data": [
{
"id": "ws-2HRvNs49EWPjDqT1",
"type": "workspaces",
"attributes": {
"name": "my-workspace",
"locked": false,
"vcs-repo": {
"identifier": "my-organization/my-repository"
}
},
"relationships": {
"organization": {
"data": {
"id": "my-organization",
"type": "organizations"
}
},
"current-run": {
"data": {
"id": "run-jm8ekSaW3F52FACN",
"type": "runs"
}
}
},
"links": {
"self": "/api/v2/organizations/my-organization/workspaces/my-workspace"
}
}
],
"links": {
"self": "http://localhost:3000/api/v2/admin/workspaces?page%5Bnumber%5D=1&page%5Bsize%5D=20",
"first": "http://localhost:3000/api/v2/admin/workspaces?page%5Bnumber%5D=1&page%5Bsize%5D=20",
"prev": null,
"next": null,
"last": "http://localhost:3000/api/v2/admin/workspaces?page%5Bnumber%5D=1&page%5Bsize%5D=20"
},
"meta": {
"pagination": {
"current-page": 1,
"prev-page": null,
"next-page": null,
"total-pages": 0,
"total-count": 1
},
"status-counts": {
"pending": 1,
"planning": 0,
"planned": 0,
"confirmed": 0,
"applying": 0,
"applied": 0,
"discarded": 0,
"errored": 0,
"canceled": 0,
"policy-checking": 0,
"policy-override": 0,
"policy-checked": 0,
"none": 0,
"total": 1,
}
}
}
Show a workspace
GET /api/v2/admin/workspaces/:id
This endpoint returns the workspace with the specified workspace_id.
| Status | Response | Reason |
|---|---|---|
| 200 | JSON API document (type: "workspaces") | Successfully listed workspaces |
| 404 | JSON API error object | Client is not an administrator. |
Query Parameters
| Parameter | Description |
|---|---|
:workspace_id | The workspace ID |
Available Related Resources
This GET endpoint can optionally return related resources, if requested with the include query parameter. The following resource types are available:
| Resource Name | Description |
|---|---|
organization | The organization for each returned workspace. |
organization.owners | A list of owners for each workspace's associated organization. |
current_run | The current run for each returned workspace. |
Sample Request
curl \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/vnd.api+json" \
"https://app.terraform.io/api/v2/admin/workspaces/ws-2HRvNs49EWPjDqT1"
Sample Response
{
"data": {
"id": "ws-2HRvNs49EWPjDqT1",
"type": "workspaces",
"attributes": {
"name": "my-workspace",
"locked": false,
"vcs-repo": {
"identifier": "my-organization/my-repository"
}
},
"relationships": {
"organization": {
"data": {
"id": "my-organization",
"type": "organizations"
}
},
"current-run": {
"data": {
"id": "run-jm8ekSaW3F52FACN",
"type": "runs"
}
}
},
"links": {
"self": "/api/v2/organizations/my-organization/workspaces/my-workspace"
}
}
}
Destroy a workspace
DELETE /admin/workspaces/:id
| Parameter | Description |
|---|---|
:workspace_id | The workspace ID |
| Status | Response | Reason |
|---|---|---|
| 204 | The workspace was successfully destroyed | |
| 404 | JSON API error object | Workspace 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/admin/workspaces/ws-2HRvNs49EWPjDqT1
Sample Response
The response body will be empty if successful.