Nodes API endpoint reference

This endpoint retrieves a list of all node IDs available in the Terraform Enterprise installation. You can use these node IDs to target specific nodes for any endpoint that supports filtering of nodes.

GET /api/v1/nodes

Sample request

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

Sample response

{
  "data": [
    "node-id-1",
    "node-id-2",
    "node-id-3"
  ],
  "links": {
    "self": "/api/v1/nodes"
  }
}

Response format

The response contains an array of node ID strings. The format of node IDs depends on the deployment environment:

Docker: Container ID
Kubernetes: Pod name
Nomad: Allocation ID
Other environments: Machine hostname

Response codes

Status	Response	Reason
200	JSON API document	Request successful
401	JSON API error object	Authentication required
500	JSON API error object	Internal 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

All system API endpoints require authentication with a bearer token generated using the tfectl admin api-token generate command. For more information on 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.

Network and port configuration

Access to the System API depends on the TFE_ADMIN_CONSOLE_ACCESS_MODE setting:

Access mode	Port	Base path	Example (`/ping`)
`port` (default)	Dedicated admin port (configured by `TFE_ADMIN_HTTPS_PORT`, defaults to `8443`)	`/api/v1`	`https://<TFE_HOSTNAME>:8443/api/v1/ping`
`path`	Standard HTTPS port (configured by `TFE_HTTPS_PORT`, defaults to `443`)	`/platform/admin/api/v1`	`https://<TFE_HOSTNAME>/platform/admin/api/v1/ping`
`both`	Either dedicated admin port or standard HTTPS port	`/api/v1` (port) or `/platform/admin/api/v1` (path)	Accessible via both endpoints

Important: When TFE_ADMIN_CONSOLE_ACCESS_MODE is set to path, Terraform Enterprise does not expose System API routes through the dedicated admin port. You must send System API requests over standard HTTPS using the /platform/admin/api/v1 prefix.

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 (or /platform/admin/api/v1 when using path mode) and is separate from the main Terraform Enterprise API.

For example, if the API endpoint documentation defines the path /ping, the full endpoint path is /api/v1/ping on the dedicated admin port, or /platform/admin/api/v1/ping when using path or both access mode.