HashiConf Last chance to register for our cloud conference October 10-12. Register today
Terraform
Terraform Home

Admin Workspaces API

The admin/workspaces API contains endpoints to help site administrators manage workspaces.

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.

List all workspaces

GET /api/v2/admin/workspaces

This endpoint lists all workspaces in the Terraform Enterprise installation.

StatusResponseReason
200JSON API document (type: "workspaces")Successfully listed workspaces
404JSON API error objectClient 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.

ParameterDescription
qOptional. 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".
sortOptional. 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 NameDescription
organizationThe organization for each returned workspace.
organization.ownersA list of owners for each workspace's associated organization.
current_runThe 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.

StatusResponseReason
200JSON API document (type: "workspaces")Successfully listed workspaces
404JSON API error objectClient is not an administrator.

Query Parameters

ParameterDescription
:workspace_idThe 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 NameDescription
organizationThe organization for each returned workspace.
organization.ownersA list of owners for each workspace's associated organization.
current_runThe 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

ParameterDescription
:workspace_idThe workspace ID
StatusResponseReason
204The workspace was successfully destroyed
404JSON API error objectWorkspace 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.

Edit this page on GitHub