/nodes 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

System API Overview

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.