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 » Admin Workspaces APITerraform 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 workspacesGET /api/v2/admin/workspaces
This endpoint lists all workspaces in the Terraform Enterprise installation.
» Query ParametersThese 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 returned workspaces. Valid values are "name"
(the default) and "current-run.created-at"
(which sorts by the time of the current run). Prepending a hyphen to the sort parameter will reverse the order (e.g. "-name"
to reverse the default order)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.
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 Requestcurl \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
"https://app.terraform.io/api/v2/admin/workspaces"
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 ,
}
}
}
{
"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 workspaceGET /api/v2/admin/workspaces/:id
This endpoint returns the workspace with the specified workspace_id
.
» Query ParametersParameter Description :workspace_id
The workspace ID
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 Requestcurl \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
"https://app.terraform.io/api/v2/admin/workspaces/ws-2HRvNs49EWPjDqT1"
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"
}
}
}
{
"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 workspaceDELETE /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 Requestcurl \
--header "Authorization: Bearer $TOKEN " \
--header "Content-Type: application/vnd.api+json" \
--request DELETE \
https://app.terraform.io/api/v2/admin/workspaces/ws-2HRvNs49EWPjDqT1
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 ResponseThe response body will be empty if successful.