Health & Metrics

Monitor the health and performance of Sphere services. Health endpoints provide instant status checks for load balancers and monitoring systems. The extended health check reveals the status of individual subsystems. Metrics expose runtime counters for observability.

All health endpoints are public and do not require authentication. They are designed to be consumed by load balancers, uptime monitors, and infrastructure tooling.

GET/auth/api/health

Auth service health

Check the health of the sphere-auth service. Returns a simple status response. This endpoint does not require authentication.

Request

GET

/auth/api/health

curl https://your-sphere.example.com/auth/api/health

Response

{
  "status": "ok",
  "version": "1.0.0"
}

GET/core/api/health

Core service health

Check the health of the sphere-core service. Returns a simple status response. This endpoint does not require authentication.

Request

GET

/core/api/health

curl https://your-sphere.example.com/core/api/health

Response

{
  "status": "ok",
  "version": "1.0.0"
}

GET/core/api/health/extended

Extended health check

Perform a comprehensive health check of all sphere-core subsystems. This checks the database connection, Redis availability, and the status of all background workers (projector, search, workflow). This endpoint does not require authentication.

The overall status field reflects the worst status among all checks:

Name
ok
Type
status
Description
All systems are operational.
Name
degraded
Type
status
Description
Some non-critical subsystems are experiencing issues. The service is still functional.
Name
down
Type
status
Description
Critical subsystems are unavailable. The service cannot process requests reliably.

Request

GET

/core/api/health/extended

curl https://your-sphere.example.com/core/api/health/extended

Response (healthy)

{
  "status": "ok",
  "checks": {
    "database": "ok",
    "redis": "ok",
    "workers": {
      "projector": "ok",
      "search": "ok",
      "workflow": "ok"
    }
  }
}

Response (degraded)

{
  "status": "degraded",
  "checks": {
    "database": "ok",
    "redis": "ok",
    "workers": {
      "projector": "ok",
      "search": "down",
      "workflow": "ok"
    }
  }
}

GET/core/api/metrics

Get metrics

Retrieve runtime metrics for the current tenant. These counters provide observability into event processing, workflow execution, and worker performance. This endpoint does not require authentication.

Metric fields

Name
events_processed
Type
integer
Description
Total number of events processed by the projector worker.
Name
workflows_executed
Type
integer
Description
Total number of workflow runs that completed successfully.
Name
workflows_failed
Type
integer
Description
Total number of workflow runs that failed during execution.
Name
worker_latency_avg_ms
Type
number
Description
Average latency of the worker pipeline in milliseconds.

Request

GET

/core/api/metrics

curl https://your-sphere.example.com/core/api/metrics

Response

{
  "data": {
    "events_processed": 48523,
    "workflows_executed": 1247,
    "workflows_failed": 3,
    "worker_latency_avg_ms": 12.4
  }
}

GET/core/api/v1/engines

List registered engines

Retrieve the list of all engines registered in the platform. Engines are the modular services that provide specific functionality (chat, VoIP, drive, mail, activity, user management). Each engine declares whether it requires tenant-level and user-level provisioning during onboarding.

This endpoint does not require authentication.

Engine properties

Name
code
Type
string
Description
Unique identifier for the engine (e.g., chat, voip, drive, mail, activity, usermanager).
Name
name
Type
string
Description
Human-readable name of the engine.
Name
url
Type
string
Description
The base URL of the engine service.
Name
is_active
Type
boolean
Description
Whether the engine is currently active and available.
Name
requires_tenant_provision
Type
boolean
Description
Whether the engine needs tenant-level provisioning when a new tenant is created.
Name
requires_user_provision
Type
boolean
Description
Whether the engine needs user-level provisioning when a new user is created.

Request

GET

/core/api/v1/engines

curl https://your-sphere.example.com/core/api/v1/engines

Response

{
  "data": [
    {
      "code": "chat",
      "name": "Chat",
      "url": "http://chat:7006",
      "is_active": true,
      "requires_tenant_provision": true,
      "requires_user_provision": true
    },
    {
      "code": "voip",
      "name": "VoIP",
      "url": "http://voip:7007",
      "is_active": true,
      "requires_tenant_provision": true,
      "requires_user_provision": true
    },
    {
      "code": "drive",
      "name": "Drive",
      "url": "http://drive:7008",
      "is_active": true,
      "requires_tenant_provision": true,
      "requires_user_provision": true
    },
    {
      "code": "mail",
      "name": "Mail",
      "url": "http://mail:7005",
      "is_active": true,
      "requires_tenant_provision": true,
      "requires_user_provision": true
    },
    {
      "code": "activity",
      "name": "Activity",
      "url": "http://activity:7009",
      "is_active": true,
      "requires_tenant_provision": true,
      "requires_user_provision": true
    },
    {
      "code": "usermanager",
      "name": "User Manager",
      "url": "http://usermanager:7004",
      "is_active": true,
      "requires_tenant_provision": true,
      "requires_user_provision": true
    }
  ]
}