#Health & Status

4 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

FieldTypeDescription
namestringAPI name
versionstringAPI version
statusstringCurrent status (online)
healthstringPath 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, and report-runtime availability. It does not validate every routed tenant data path.

#Status Codes

StatusMeaning
200 OKOverall status is healthy; the required core dependency checks passed
503 Service UnavailableOverall 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.

#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.

FieldTypeDescription
statusstringSystem health status: healthy or unhealthy
versionstringApplication version from system/version.txt
databaseobjectLocal API metadata store connectivity and writability status
database.statusstringconnected or error
database.db_writablebooleantrue when SELECT NOT pg_is_in_recovery() reports the local API database is writable; present when the database check completes
database.messagestringError detail when the database check fails; only status and message are returned in that case
billingobjectLocal billing configuration readiness status; included for visibility and not used for overall health
billing.statusstringconnected or error
billing.codestringBilling readiness code when available, for example ok or billing_configuration_invalid
billing.messagestringBilling readiness message
billing.checked_at_utcstringUTC timestamp for the billing readiness check when available
reports_runtimeobjectLocal Reports v5.3 schedule-runtime table visibility status; included for visibility and not used for overall health
reports_runtime.statusstringconnected, degraded, or error
reports_runtime.schedules_tablebooleantrue when public.portal_report_schedules_current exists (to_regclass is not null)
reports_runtime.deliveries_tablebooleantrue when public.portal_report_deliveries_v2 exists (to_regclass is not null)
reports_runtime.messagestringError detail when the report-runtime visibility check fails

#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
  }
}

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"
  }
}