#Health & Status

5 min read

Check API availability and system health. These endpoints are public and do not require authentication.

Production API: https://api.aidial.ai

#`GET /`

Returns API metadata and status.

Authentication: None required

#Response

Field	Type	Description
`name`	string	API name
`version`	string	API version
`status`	string	Current status (`online`)
`health`	string	Path to the health check endpoint

#Example

Request:

Bash

curl -X GET "https://api.aidial.ai/"

Response (200 OK):

JSON

{
  "name": "AiDial API",
  "version": "1.0.0",
  "status": "online",
  "health": "/v1/health"
}

#`GET /v1/health`

Returns API runtime health and readiness details. Use this endpoint for uptime monitoring, deployment verification, and database-readiness checks.

Authentication: None required

The endpoint checks core API dependencies, billing readiness, report-runtime availability, and usage billing runner readiness. It does not validate every routed tenant data path.

#Status Codes

Status	Meaning
`200 OK`	Overall status is `healthy`; the required core dependency checks passed
`503 Service Unavailable`	Overall status is `unhealthy`; a required core dependency check failed

database.db_writable reports whether the local API metadata store is writable. It is included for HA readiness and failover monitoring. Treat false as a database-role/readiness signal even when database connectivity is present.

billing is reported for operational visibility. It verifies local billing configuration readiness only: required provider credentials and mode are valid, and the billing provider client can be initialized. It does not call billing provider APIs from the health path. The readiness result is cached for a short interval, so the health endpoint may return a recently computed result rather than rechecking the configuration on every request; billing.checked_at_utc reports when that result was produced. A billing readiness error appears in the response body, but billing status does not currently determine the endpoint's 200 or 503 result.

reports_runtime is also reported for operational visibility. It checks whether the Reports v5.3 schedule and delivery tables are present and queryable in the local API metadata store. A degraded or error report-runtime status appears in the response body, but report-runtime status does not currently determine the endpoint's 200 or 503 result.

pricing_runner is also reported for operational visibility. It reports whether the usage billing runner's provider credential is configured for this environment, how long ago the runner last completed a full pass, and how long the oldest invoice it holds for operator review has been held. It does not call billing provider APIs from the health path. not_ready is expected while the runner's credential is not configured, and a null pass age is normal until the first full pass after the API starts. Alert on the two ages growing; pricing-runner status does not determine the endpoint's 200 or 503 result.

#Response

The response also carries internal dependency diagnostic fields for operator monitoring, some of which contribute to overall health. Those fields are not part of the published contract, are omitted from the table and examples below, and may change without notice.

Field	Type	Description
`status`	string	System health status: `healthy` or `unhealthy`
`version`	string	Application version from `system/version.txt`
`database`	object	Local API metadata store connectivity and writability status
`database.status`	string	`connected` or `error`
`database.db_writable`	boolean	`true` when `SELECT NOT pg_is_in_recovery()` reports the local API database is writable; present when the database check completes
`database.message`	string	Error detail when the database check fails; only `status` and `message` are returned in that case
`billing`	object	Local billing configuration readiness status; included for visibility and not used for overall health
`billing.status`	string	`connected` or `error`
`billing.code`	string	Billing readiness code when available, for example `ok` or `billing_configuration_invalid`
`billing.message`	string	Billing readiness message
`billing.checked_at_utc`	string	UTC timestamp for the billing readiness check when available
`reports_runtime`	object	Local Reports v5.3 schedule-runtime table visibility status; included for visibility and not used for overall health
`reports_runtime.status`	string	`connected`, `degraded`, or `error`
`reports_runtime.schedules_table`	boolean	`true` when `public.portal_report_schedules_current` exists (`to_regclass` is not null)
`reports_runtime.deliveries_table`	boolean	`true` when `public.portal_report_deliveries_v2` exists (`to_regclass` is not null)
`reports_runtime.message`	string	Error detail when the report-runtime visibility check fails
`pricing_runner`	object	Usage billing runner readiness; included for visibility and not used for overall health
`pricing_runner.status`	string	`ready` or `not_ready`
`pricing_runner.code`	string	`ok`, `key_unavailable` (credential not configured), `key_mode_conflict` (credential does not match this environment's billing mode), or `source_unavailable` (runner state could not be read)
`pricing_runner.last_good_tick_age_seconds`	integer or null	Seconds since the runner last completed a pass without errors; `null` when none has completed since the API started
`pricing_runner.oldest_held_invoice_age_seconds`	integer or null	Seconds the oldest unresolved held invoice period has been open; `null` when none is held or the state could not be read

#Example

Request:

Bash

curl -X GET "https://api.aidial.ai/v1/health"

Response (200 OK — system healthy):

JSON

{
  "status": "healthy",
  "version": "1.0.640",
  "database": {
    "status": "connected",
    "db_writable": true
  },
  "billing": {
    "status": "connected",
    "code": "ok",
    "message": "Billing configuration is ready. Stripe provider access is validated by billing endpoints.",
    "checked_at_utc": "2026-04-17T00:00:00Z"
  },
  "reports_runtime": {
    "status": "connected",
    "schedules_table": true,
    "deliveries_table": true
  },
  "pricing_runner": {
    "status": "not_ready",
    "code": "key_unavailable",
    "last_good_tick_age_seconds": 42,
    "oldest_held_invoice_age_seconds": null
  }
}

Response (503 Service Unavailable — system unhealthy because a required health check failed):

JSON

{
  "status": "unhealthy",
  "version": "1.0.640",
  "database": {
    "status": "error",
    "message": "Connection refused"
  },
  "billing": {
    "status": "error",
    "code": "billing_configuration_invalid",
    "message": "Billing Stripe key has the wrong restricted key mode.",
    "checked_at_utc": "2026-04-17T00:00:00Z"
  },
  "reports_runtime": {
    "status": "error",
    "message": "Connection refused"
  },
  "pricing_runner": {
    "status": "not_ready",
    "code": "source_unavailable",
    "last_good_tick_age_seconds": null,
    "oldest_held_invoice_age_seconds": null
  }
}

API Reference — endpoint index and base URL
Error Responses — error format details

Start

Guides

Authentication

Features

Client Guides

Partner Guides

#Health & Status

#`GET /`

#Response

#Example

#`GET /v1/health`

#Status Codes

#Response

#Example

#Health & Status

#GET /

#Response

#Example

#GET /v1/health

#Status Codes

#Response

#Example

#Related Pages

#`GET /`

#`GET /v1/health`