Readiness endpoint

Terraform Enterprise provides two readiness endpoints that check if nodes are ready to accept requests. Both endpoints perform quick health checks of critical subsystems and return the current readiness status.

• /api/v1/health/readiness: This endpoint checks readiness of a single node and is served on the application port. Because this endpoint targets a specific node, you should send the request directly to the node instead of through a load balancer. Refer to Check single-node readiness for details.
• /api/v1/nodes/readiness: This endpoint checks the readiness of all active nodes in the deployment and is served on the admin console port. By default, the admin console port is 8443. This endpoint requires authentication. Refer to Check multi-node readiness for details.

Check single-node readiness

This endpoint checks the readiness of the individual node that receives the request. Because this endpoint targets a specific node, you should send the request directly to the node instead of through a load balancer.

GET /api/v1/health/readiness

Query parameters

Sample request

curl \
  --request GET \
  "https://tfe.example.com/api/v1/health/readiness?timeout=5"

Readiness registry checks

Both readiness endpoints check the following subsystems. For a complete list of Terraform Enterprise services, refer to the services reference.

Single-node response

The endpoint returns the readiness status in JSON format by default. For requests with Accept header containing text/plain or text/html, it returns plain text.

JSON response

Sample JSON response

{
  "node": "84ebea16aab1",
  "status": "ERROR",
  "checks": [
    {
      "check": "archivist",
      "status": "OK"
    },
    {
      "check": "atlas",
      "status": "ERROR"
    },
    {
      "check": "database",
      "status": "OK"
    },
    {
      "check": "disk",
      "status": "OK"
    },
    {
      "check": "redis",
      "status": "OK"
    },
    {
      "check": "task-worker",
      "status": "ERROR"
    },
    {
      "check": "vault",
      "status": "OK"
    }
  ]
}

Plain text response

Returns the overall status as plain text: OK, ERROR, or DRAINING.

Single-node response codes

Check multi-node readiness

The multi-node readiness endpoint aggregates readiness check results from all active nodes in a Terraform Enterprise deployment. It returns node-level readiness status in a single authenticated request, so you do not need to query each node individually. Authentication is required to use this endpoint.

This endpoint is useful for monitoring deployment health and for powering the admin console system health overview.

GET /api/v1/nodes/readiness

Query parameters

Sample request

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

Sample response

[
  {
    "node": "node-id-1",
    "status": "ERROR",
    "checks": [
      {
        "check": "archivist",
        "status": "ERROR"
      },
      {
        "check": "atlas",
        "status": "ERROR"
      },
      {
        "check": "database",
        "status": "OK"
      },
      {
        "check": "redis",
        "status": "OK"
      },
      {
        "check": "task-worker",
        "status": "OK"
      },
      {
        "check": "vault",
        "status": "OK"
      }
    ]
  },
  {
    "node": "node-id-2",
    "status": "OK",
    "checks": [
      {
        "check": "archivist",
        "status": "OK"
      },
      {
        "check": "atlas",
        "status": "OK"
      },
      {
        "check": "database",
        "status": "OK"
      },
      {
        "check": "redis",
        "status": "OK"
      },
      {
        "check": "task-worker",
        "status": "OK"
      },
      {
        "check": "vault",
        "status": "OK"
      }
    ]
  }
]

Response attributes

The endpoint returns an array of readiness results. Each element represents one active node in the deployment.

The status field reflects the highest severity across all subsystem checks for the node. ERROR takes precedence over DRAINING, which takes precedence over OK.

The response includes nodes that fail to execute readiness checks as well as the appropriate error information.

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

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.

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.