HashiConf 2025 Don't miss the live stream of HashiConf Day 2 happening now View live stream
Terraform
Terraform Home

Support bundle requests API reference

A support bundle contains diagnostic information that helps troubleshoot issues with a Terraform Enterprise installation. Refer to the tfectl command documentation for instructions on how to generate a support bundle using tfectl.

Generate support bundle

This endpoint creates a new support bundle request that collects diagnostic information from one or more Terraform Enterprise nodes. Authentication is required to use this endpoint.

POST /api/v1/support/bundle-requests

Request body

ParameterTypeDescription
nodesarray of stringsOptional. List of node identifiers to generate bundles from specific nodes. If not specified, the bundle generates from all nodes in the Terraform Enterprise installation.

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://tfe.example.com:8443/api/v1/support/bundle-requests

Sample payload

{
  "nodes": ["node-id-1", "node-id-2"]
}

Sample response

{
  "data": {
    "id": "2025-09-26T09:21:06Z",
    "type": "support-bundle",
    "attributes": {
      "status": "generating",
      "created_at": "2025-05-08T10:15:30Z",
      "nodes": ["node-id-1", "node-id-2"]
    },
    "links": {
      "self": "/support/bundle-requests/2025-05-08T10:15:30Z"
    }
  }
}

The id returned is the identifier for the support bundle request. Use this ID to query status, download the resulting bundle, or perform other operations related to this request.

Response codes

StatusResponseReason
202JSON API documentRequest accepted, bundle generation started
400JSON API error objectInvalid request parameters
401JSON API error objectAuthentication required
404JSON API error objectSpecified node ID not found
429JSON API error objectToo many requests. Wait before retrying.
500JSON API error objectInternal server error

List support bundle requests

This endpoint retrieves a paginated list of support bundle requests with their current status. You can filter results by creation date, status, and node IDs. Authentication is required to use this endpoint.

GET /api/v1/support/bundle-requests

Query parameters

ParameterTypeDescription
filter[created_after]datetimeFilter bundles created after this date
filter[created_before]datetimeFilter bundles created before this date
filter[status]stringFilter by status: generating, finished, or errored
filter[nodes]array of stringsFilter to show bundles that include the specified node IDs
page[number]integerPage number for pagination. Default is 1.
page[size]integerNumber of items per page. Default is 20. Maximum is 100.

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --request GET \
  "https://tfe.example.com:8443/api/v1/support/bundle-requests"

Sample response

{
  "data": [
    {
      "id": "2025-05-07T14:30:00Z",
      "type": "support-bundle",
      "attributes": {
        "status": "finished",
        "created_at": "2025-05-07T14:30:00Z",
        "completed_at": "2025-05-07T14:35:12Z",
        "size_bytes": 15728640,
        "nodes": [
          {
            "node": "node-id-1",
            "status": "finished",
            "size_bytes": 7864320,
            "error": null,
            "completed_at": "2025-05-07T14:32:45Z"
          },
          {
            "node": "node-id-2",
            "status": "finished",
            "size_bytes": 7864320,
            "error": null,
            "completed_at": "2025-05-07T14:35:12Z"
          }
        ]
      },
      "links": {
        "self": "/support/bundle-requests/2025-05-07T14:30:00Z",
        "download": "/support/bundle-requests/2025-05-07T14:30:00Z/download"
      }
    },
    {
      "id": "2025-05-08T10:15:30Z",
      "type": "support-bundle",
      "attributes": {
        "status": "generating",
        "created_at": "2025-05-08T10:15:30Z",
        "nodes": [
          {
            "node": "node-id-1",
            "status": "generating",
            "error": null
          }
        ]
      },
      "links": {
        "self": "/support/bundle-requests/2025-05-08T10:15:30Z"
      }
    },
    {
      "id": "2025-05-08T10:15:30Z",
      "type": "support-bundle",
      "attributes": {
        "status": "errored",
        "created_at": "2025-05-08T10:15:30Z",
        "completed_at": "2025-05-08T10:16:45Z",
        "nodes": [
          {
            "node": "node-id-1",
            "status": "errored",
            "error": "Connection timeout",
            "completed_at": "2025-05-08T10:16:45Z"
          },
          {
            "node": "node-id-2",
            "status": "finished",
            "size_bytes": 7864320,
            "error": null,
            "completed_at": "2025-05-08T10:16:45Z"
          }
        ],
        "error": "Bundle generation failed on node-id-1: Connection timeout"
      },
      "links": {
        "self": "/support/bundle-requests/2025-05-08T10:15:30Z"
      }
    }
  ],
  "meta": {
    "pagination": {
      "current_page": 1,
      "total_pages": 5,
      "total_count": 48
    }
  },
  "links": {
    "self": "/support/bundle-requests?page[number]=1&page[size]=10",
    "first": "/support/bundle-requests?page[number]=1&page[size]=10",
    "prev": null,
    "next": "/support/bundle-requests?page[number]=2&page[size]=10",
    "last": "/support/bundle-requests?page[number]=5&page[size]=10"
  }
}

Response attributes

AttributeTypeDescription
idstringUnique identifier for the support bundle request
statusstringCurrent status: generating, finished, or errored
created_atdatetimeWhen the bundle request was created
completed_atdatetimeWhen the bundle generation completed. This attribute is only applies to bundles with a finished or errored status.
size_bytesintegerTotal size of the bundle in bytes. This attribute is only applies to bundles with a finished status.
nodesarray of objectsDetailed status information for each node in the bundle
nodes[].nodestringNode identifier
nodes[].statusstringStatus for this specific node: generating, finished, or errored
nodes[].size_bytesintegerSize of the bundle from this node in bytes. This attribute only applies to nodes with a finished status.
nodes[].errorstringError message for this node. This attribute is only for errored nodes.
nodes[].completed_atdatetimeWhen bundle generation completed for this node. This attribute only applies to nodes with a finished or errored status.
errorstringError message. This attribute only applies to nodes with an errored status.

Response codes

StatusResponseReason
200JSON API documentRequest successful
400JSON API error objectInvalid request parameters
401JSON API error objectAuthentication required
500JSON API error objectInternal server error

Get support bundle details

This endpoint retrieves detailed information about a specific support bundle request, including per-node status information. Authentication is required to use this endpoint.

GET /api/v1/support/bundle-requests/:id

Path parameters

ParameterTypeDescription
idstringSupport bundle request identifier

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --request GET \
  "https://tfe.example.com:8443/api/v1/support/bundle-requests/2025-09-26T09:21:06Z"

Sample response

{
  "data": {
    "id": "2025-09-26T09:21:06Z",
    "type": "support-bundle",
    "attributes": {
      "status": "finished",
      "created_at": "2025-05-07T14:30:00Z",
      "completed_at": "2025-05-07T14:35:12Z",
      "size_bytes": 15728640,
      "error": null,
      "nodes": [
        {
          "node": "node-id-1",
          "status": "finished",
          "size_bytes": 7864320,
          "error": null,
          "completed_at": "2025-05-07T14:32:45Z"
        },
        {
          "node": "node-id-2",
          "status": "finished",
          "size_bytes": 7864320,
          "error": null,
          "completed_at": "2025-05-07T14:35:12Z"
        }
      ]
    },
    "links": {
      "self": "/support/bundle-requests/2025-09-26T09:21:06Z",
      "download": "/support/bundle-requests/2025-09-26T09:21:06Z/download"
    }
  }
}

Response attributes

The response includes all attributes from the list endpoint, plus detailed per-node information:

AttributeTypeDescription
idstringUnique identifier for the support bundle request
statusstringOverall status of the bundle request: generating, finished, or errored. If one or more nodes are errored, the overall status is errored. If one or more nodes are generating, the overall status is generating. Otherwise, the status is finished.
created_atdatetimeWhen the bundle request was created
completed_atdatetimeWhen all bundle generation completed across all nodes. This attribute only applies to finished and errored bundles.
size_bytesintegerTotal size of all bundles from all nodes in bytes. This attribute only applies to bundles with a finished status.
errorstringOverall error message if any node failed during generation. This attribute only applies to bundles with an errored status.
nodesarray of objectsDetailed status information for each node in the bundle
nodes[].nodestringNode identifier
nodes[].statusstringStatus for this specific node: generating, finished, or errored.
nodes[].size_bytesintegerSize of the bundle from this node in bytes. This attribute only applies to nodes with a finished status.
nodes[].errorstringError message for this node. This attribute only applies to nodes with an errored status.
nodes[].completed_atdatetimeWhen bundle generation completed for this node. This attribute only applies to nodes with a finished or errored status.

Response codes

StatusResponseReason
200JSON API documentRequest successful
401JSON API error objectAuthentication required
404JSON API error objectSpecified support bundle request ID not found
500JSON API error objectInternal server error

Download support bundle

This endpoint downloads a gzip-compressed tarball for a completed support bundle. Authentication is required to use this endpoint.

GET /api/v1/support/bundle-requests/:id/download

Path and query parameters

ParameterTypeDescription
idstring (path)Support bundle request identifier
nodesarray of strings (query)Optional. When specified, download only the bundle files for these node IDs. Repeat the nodes parameter for multiple nodes, for example: ?nodes=node-id-1&nodes=node-id-2.

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --request GET \
  "https://tfe.example.com:8443/api/v1/support/bundle-requests/2025-05-07T14:30:00Z/download?nodes=node-id-1&nodes=node-id-2"

Success response

Example downloaded bundle structure:

support-bundle-550e8400-e29b-41d4-a716-446655440000.tar.gz
└── 2025-05-08T10:15:30Z
    ├── node-id-1
    │   └── node-id-1-support-bundle-2025-05-08T10:15:30Z.tar.gz
    └── node-id-2
        └── node-id-2-support-bundle-2025-05-08T10:15:30Z.tar.gz

Response codes

StatusResponseReason
200Binary tar.gzRequest successful
400JSON API error objectInvalid request parameters
401JSON API error objectAuthentication required
404JSON API error objectSpecified support bundle request ID not found
409JSON API error objectSupport bundle is still generating
[410][]JSON API error objectSupport bundle has been deleted and is no longer available
500JSON API error objectInternal server error

Delete support bundle

This endpoint permanently removes a support bundle request and any generated bundles from the server. Authentication is required to use this endpoint.

DELETE /api/v1/support/bundle-requests/:id

Path and query parameters

ParameterTypeDescription
idstring (path)Support bundle request identifier

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --request DELETE \
  "https://tfe.example.com:8443/api/v1/support/bundle-requests/2025-09-26T09:21:06Z"

Success response

  • Status: 204 No Content

Response codes

StatusResponseReason
204No ContentRequest successful
401JSON API error objectAuthentication required
404JSON API error objectSpecified support bundle request ID not found
409JSON API error objectSupport bundle is still generating
[410][]JSON API error objectSupport bundle has been deleted and is no longer available
500JSON API error objectInternal server error

System API Overview

Terraform Enterprise Only: The System API is exclusive to Terraform Enterprise. It enables access to deployment configuration and data.

This API is distinct from the regular Admin API and the Backup and Restore API, with its own authentication mechanism.

Authentication

Requests to the /api/v1/ping and /api/v1/usage/bundle endpoints must be authenticated with a bearer token generated specifically for them using the tfectl admin api-token generate command. For more information on the token creation, and management, refer to the tfectl documentation.

Use the HTTP Header Authorization with the value Bearer <token>.

Rate Limiting

All System API endpoints are rate limited to 1 request per second per authentication token.

Port Configuration

By default, the System API is accessible on HTTPS port 8443. This port can be configured through the TFE_ADMIN_HTTPS_PORT environment variable in your deployment configuration.

Refer to Network settings in the configuration reference for more information about network configuration.

Versioning

The System API is versioned under the /api/v1 prefix and is separate from the main Terraform Enterprise API.

For example, if the API endpoint documentation defines the path /ping then the full path is /api/v1/ping.

Edit this page on GitHub