AimableDocs
DocsAPI ReferenceRelease Notes

General

Updated 9 July 2026

General

The General domain of the Aimable Platform API (v0.1.0) provides foundational endpoints for system health checks and version discovery. These endpoints are essential for monitoring, debugging, and ensuring compatibility across services in distributed environments. They are typically used by DevOps teams, platform administrators, and developers integrating with the Aimable ecosystem.

While these endpoints don’t manage business data, they are critical for operational visibility and service reliability. They help confirm API availability, verify deployment integrity, and support automated health checks in CI/CD pipelines or container orchestration platforms like Kubernetes.

Key Concepts

  • Health Check (/health, /v1/health): Lightweight endpoints that return 200 OK when the API is reachable and functioning. Used for liveness and readiness probes.
  • System Versions (/system/versions): Returns version information for all internal services. Useful for debugging, ensuring correct deployments, and tracking service-level compatibility.

These endpoints require no request body and return simple JSON responses. They are read-only and do not modify system state.

How to Use the Endpoints

1. Health Check (v0 and v1)

Check if the API is up and responding.

Endpoint:
GET /api/health
GET /api/v1/health

Example Request:

bash
curl -X GET https://platform.aimable.com/api/health \
  -H "Authorization: Bearer <your-access-token>"

Response (200 OK):

json
{
  "status": "healthy",
  "message": "Service is operational"
}

Tip: Use /health in load balancer health probes or container liveness checks.

2. Get System Versions

Retrieve deployed versions of all internal services.

Endpoint:
GET /api/system/versions

Example Request:

bash
curl -X GET https://platform.aimable.com/api/system/versions \
  -H "Authorization: Bearer <your-access-token>"

Response (200 OK):

json
{
  "api_gateway": "v0.1.0",
  "user_service": "v0.2.3",
  "content_service": "v0.1.8",
  "auth_service": "v0.3.1",
  "timestamp": "2023-10-05T12:34:56Z"
}

Use case: After a deployment, call this endpoint to verify that all services are running the expected versions.

Common Workflows

✅ Service Startup and Readiness

When deploying a client application or microservice that depends on Aimable Platform, follow this sequence:

  1. Check health to confirm connectivity:

    bash
    curl -s -o /dev/null -w "%{http_code}" https://platform.aimable.com/api/health

    If response is 200, proceed.

  2. Fetch system versions to validate environment:

    bash
    curl https://platform.aimable.com/api/system/versions \
  -H "Authorization: Bearer <token>"

    Confirm the versions match your integration requirements.

This workflow ensures your client is interacting with a live and correctly deployed platform.

🔄 Monitoring and Alerting

Set up automated health checks every 30–60 seconds using /health. If the endpoint returns anything other than 200, trigger alerts. Optionally, pair with /system/versions to detect unexpected rollbacks or version drift.

See Authentication & errors for request authentication and the standard error responses.

Summary

The General domain provides essential operational insights into the Aimable Platform API. Use /health for uptime monitoring and /system/versions for deployment validation. These endpoints are small but powerful tools for ensuring reliability and consistency in production environments.

Related Endpoints

See also