Readiness endpoint

The readiness endpoint checks if Terraform Enterprise is ready to accept requests. It performs a quick health check of critical subsystems and returns the current readiness status.

Endpoint

GET /api/v1/health/readiness

Query parameters

Parameter	Type	Description
`timeout`	integer	Optional. Timeout in seconds for the readiness check. Valid range is `1`-`30`. Default is `1`.

Sample request

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

Readiness Registry Checks

Subsytem	What it Checks
Archivist	Ensures backend storage connectivity
Atlas	Validates Atlas Rails application health endpoint connectivity
Vault	Validates that Vault is initialized, sealed (or unsealed) and active
Database	Fast connectivity test to PostgreSQL (no version/extension validation, no retries)
Redis	Fast connectivity test to Redis (no retry, no validation)
Task Worker	Checks if task worker is in draining state
Disk	Verifies disk path exists and is accessible (disk operational mode only)

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

Attribute	Type	Description
`node`	string	Name of the node that performed the check
`status`	string	Overall readiness status: `OK`, `ERROR`, or `DRAINING`
`checks`	array of objects	Detailed status for each subsystem check
`checks[].check`	string	Name of the subsystem being checked
`checks[].status`	string	Status of the check: `OK` or `ERROR`

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.

Response codes

Status	Response	Reason
200	JSON API document or plain text	Terraform Enterprise is ready
400	JSON API error object error	Invalid timeout parameter
503	JSON API document or plain text	Terraform Enterprise is not ready or draining