Health Status Overview

The DynamoAI API provides a health status endpoint that allows you to monitor the connectivity and operational status of various system components and dependencies. This endpoint performs health checks to verify that the API can successfully communicate with critical services and infrastructure components.

Endpoint

The health status endpoint is available at:

GET /health/status

Response Format

The endpoint returns a JSON response with the following structure:

{
    "status": "ok",
    "info": {
        "mongodb": {
            "status": "up",
        },
        "postgres-app": {
            "status": "up"
        },
        "postgres-keycloak": {
            "status": "up"
        },
        "redis": {
            "status": "up"
        },
        "keycloak": {
            "status": "up"
        },
        "flower": {
            "status": "up"
        },
        "moderation": {
            "status": "up"
        },
        "s3": {
            "status": "up"
        }
    },
    "error": {},
    "details": {
        "mongodb": {
            "status": "up",
        },
        "postgres-app": {
            "status": "up"
        },
        "postgres-keycloak": {
            "status": "up"
        },
        "redis": {
            "status": "up"
        },
        "keycloak": {
            "status": "up"
        },
        "flower": {
            "status": "up"
        },
        "moderation": {
            "status": "up"
        },
        "s3": {
            "status": "up"
        }
    }
}

Response Fields

status

The overall health status of the system. Possible values:

• "ok" - All checked components are operational
• "error" - One or more components are experiencing issues

info

Contains the status information for each component that is currently operational (status: "up").

error

Contains information about any components that are experiencing issues. This object will be empty when all components are healthy.

details

Provides detailed status information for all checked components, regardless of their health status.

Monitored Components

The health status endpoint checks the connectivity and operational status of the following components. Each health check uses a consistent timeout (2000ms / 2 seconds) and error handling mechanism.

Component	Description	Check Method	Details
mongodb	MongoDB database	MongoDB admin().ping() command	Lightweight ping operation that confirms connectivity
postgres-app	Main application PostgreSQL database	Queries pg_database system catalog	Query: SELECT datname FROM pg_database WHERE datname = '<POSTGRES_DB_NAME>' LIMIT 1
postgres-keycloak	Keycloak PostgreSQL database	Queries pg_database system catalog	Query: SELECT datname FROM pg_database WHERE datname = '<KEYCLOAK_DB_NAME>' LIMIT 1
redis	Redis cache and message broker	Executes Redis PING command	Standard Redis ping to test connectivity
keycloak	Keycloak authentication service	HTTP GET request to Keycloak's /health/ready endpoint	Endpoint: ${KEYCLOAK_BASE_URL}/health/ready
flower	Flower monitoring service for Celery tasks	HTTP GET request to Flower's /api/workers endpoint	Endpoint: ${FLOWER_BASE_URL}/api/workers Authentication: Basic Auth using FLOWER_AUTH_TOKEN
moderation	DynamoGuard Moderation service	HTTP GET request to moderation worker's /ping endpoint	Endpoint: http://${MODERATOR_WORKER_ASYNC_ENDPOINT}/ping Note: Returns "down" status if MODERATOR_WORKER_ASYNC_ENDPOINT is not configured
s3	AWS S3 storage service	Executes AWS S3 ListBuckets command	Lightweight operation that confirms AWS credentials and network connectivity

Component Status Values

Each component in the response can have one of the following status values:

• "up" - The component is operational and the API can successfully communicate with it
• "down" - The component is not responding or the API cannot communicate with it

Timeout and Error Handling

Timeout Protection

All health checks implement timeout protection to prevent hanging:

• Default Timeout: 2000ms (2 seconds)
• Implementation: Uses Promise.race() to enforce timeouts
• Behavior: If a health check exceeds the timeout, it is marked as "down"

Error Handling

• Common Handling: All health checks use consistent timeout and error handling mechanisms
• Error Logging: All health check failures are logged with detailed error information
• Response Format: Health checks return structured results indicating "up" or "down" status

Health Check Result Format

{
  "status": "ok" | "error",
  "info": {
    "component-name": {
      "status": "up" | "down",
      "message": "optional error message"
    }
  },
  "error": {
    "component-name": {
      "status": "down",
      "message": "error details"
    }
  }
}

Notes

• The endpoint performs connectivity checks to verify that the API can communicate with each component
• A component showing "up" indicates successful connectivity, not necessarily that the component is fully operational
• The mongodb component status will be included in the response once MongoDB is deployed in your environment
• The endpoint does not require authentication and is typically used for infrastructure monitoring purposes