#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 the API host's local API metadata store, secret-service proxy, billing readiness, and report-runtime table visibility. It does not validate every routed tenant data-store path or tunnel.

#Status Codes

StatusMeaning
200 OKOverall status is healthy; the local API database and secret-service checks are connected
503 Service UnavailableOverall status is unhealthy; the local API database or secret backend 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: the secret service can supply the Stripe restricted key, the key has the expected restricted-key prefix, and the Stripe SDK can be initialized. It does not call Stripe provider APIs from the health path. 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

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.status_detailstringconnected or error when the local API database query runs
database.db_writablebooleantrue when SELECT NOT pg_is_in_recovery() reports the local API database is writable
database.hoststring or nullDatabase host label when the database check succeeds
database.messagestringError detail when the database check fails
secret_serviceobjectsecret-service proxy connectivity status
secret_service.statusstringconnected or error
secret_service.hoststringsecret-service proxy host when the check succeeds
secret_service.messagestringError detail when secret-service configuration or connectivity fails
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 and is queryable
reports_runtime.deliveries_tablebooleantrue when public.portal_report_deliveries_v2 exists and is queryable
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.635",
  "database": {
    "status": "connected",
    "status_detail": "connected",
    "db_writable": true,
    "host": "db"
  },
  "secret_service": {
    "status": "connected",
    "host": "secret-service"
  },
  "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.635",
  "database": {
    "status": "error",
    "message": "Connection refused"
  },
  "secret_service": {
    "status": "connected",
    "host": "secret-service"
  },
  "billing": {
    "status": "error",
    "code": "billing_configuration_invalid",
    "message": "Billing Stripe key must be a restricted key.",
    "checked_at_utc": "2026-04-17T00:00:00Z"
  },
  "reports_runtime": {
    "status": "error",
    "message": "Connection refused"
  }
}