/ping endpoint reference
This endpoint provides a simple health check to verify that the Terraform Enterprise system is operational. Authentication is required to use this endpoint.
GET /api/v1/ping
Sample request
curl \
--header "Authorization: Bearer $TOKEN" \
--request GET \
https://tfe.example.com:8443/api/v1/ping
Sample Response
"pong"
Response codes
| Status | Response | Reason |
|---|---|---|
| 200 | pong | The system is operational |
| 403 | JSON API error object | Not authorized to access this endpoint |
| 429 | JSON API error object | Too many requests |
| 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.