System

The System API provides endpoints for monitoring API health, checking system status, and retrieving operational information. These endpoints are useful for load balancers, monitoring systems, and operational dashboards.

Health Check

GET/health
Auth required

Returns a simple health status to verify the API is responding. This endpoint doesn't require authentication and consumes no credits.

Response

OK

Health Check Usage

Use this endpoint for:

  • Load balancer health checks
  • Kubernetes readiness probes
  • Monitoring system pings
  • Basic connectivity testing

This endpoint is designed to be fast and lightweight.


System Information

GET/system
Auth required

Returns comprehensive system information including version details, event statistics, and operational metrics. This endpoint requires authentication.

Response

{
  "version": "1.0.0",
  "status": "healthy",
  "uptime": "7 days, 4 hours, 23 minutes",
  "timestamp": "2024-01-31T15:30:45Z",
  "event_stats": {
    "total_events": 15420,
    "events_last_24h": 234,
    "events_by_type": {
      "account.created": 1250,
      "transaction.posted": 8900,
      "invoice.created": 2340,
      "contact.updated": 1200,
      "organization.created": 45,
      "system.initialized": 1
    },
    "recent_events": [
      {
        "id": "evt_xxxxxxxxxxxxxxxx",
        "event_type": "transaction.posted",
        "entity_type": "transaction",
        "entity_id": "txn_xxxxxxxxxxxxxxxx",
        "timestamp": "2024-01-31T15:29:12Z"
      },
      {
        "id": "evt_yyyyyyyyyyyyyyyy",
        "event_type": "invoice.created",
        "entity_type": "invoice",
        "entity_id": "inv_xxxxxxxxxxxxxxxx",
        "timestamp": "2024-01-31T15:28:45Z"
      }
    ]
  },
  "database": {
    "status": "connected",
    "connection_pool_size": 10,
    "active_connections": 3,
    "pending_queries": 0
  },
  "workers": {
    "status": "operational",
    "active_workers": 8,
    "queued_jobs": 12,
    "completed_jobs_24h": 1250,
    "failed_jobs_24h": 2
  },
  "cache": {
    "status": "operational",
    "hit_rate": 0.87,
    "memory_usage": "45MB",
    "keys_count": 15432
  }
}

Response Fields

FieldTypeDescription
versionstringAPI version number
statusstringOverall system status (healthy, degraded, maintenance)
uptimestringHow long the system has been running
timestampstringCurrent server timestamp
event_statsobjectComprehensive event system statistics
databaseobjectDatabase connection and performance metrics
workersobjectBackground worker system status
cacheobjectCaching system performance metrics

Event Statistics Details

The event_stats object provides detailed information about the event system:

FieldDescription
total_eventsTotal number of events in the system
events_last_24hEvents created in the last 24 hours
events_by_typeBreakdown of events by type
recent_eventsLast 10 events with basic information

System Status Values

StatusDescriptionAction Required
healthyAll systems operationalNone
degradedSome systems experiencing issuesMonitor closely
maintenanceSystem under maintenanceAPI may be unavailable

Monitoring Integration

Load Balancer Configuration

Use the health check endpoint for load balancer health checks:

# Nginx load balancer configuration
upstream craneledger_api {
    server api1.craneledger.ai:443;
    server api2.craneledger.ai:443;
    server api3.craneledger.ai:443;
}

server {
    listen 443 ssl;
    server_name api.craneledger.ai;

    location /health {
        proxy_pass https://craneledger_api;
        proxy_connect_timeout 5s;
        proxy_send_timeout 5s;
        proxy_read_timeout 5s;

        # Return 200 for OK, 503 for anything else
        if ($upstream_response_time = "") {
            return 503;
        }
    }

    location / {
        proxy_pass https://craneledger_api;
    }
}

Kubernetes Readiness Probe

apiVersion: v1
kind: Pod
metadata:
  name: craneledger-api
spec:
  containers:
  - name: api
    image: craneledger/api:latest
    ports:
    - containerPort: 8080
    readinessProbe:
      httpGet:
        path: /health
        port: 8080
      initialDelaySeconds: 5
      periodSeconds: 10
      timeoutSeconds: 5
      successThreshold: 1
      failureThreshold: 3
    livenessProbe:
      httpGet:
        path: /system
        port: 8080
        httpHeaders:
        - name: Authorization
          value: "Bearer your_monitoring_token"
      initialDelaySeconds: 30
      periodSeconds: 30
      timeoutSeconds: 10

Prometheus Monitoring

Metrics Endpoint

The /system/metrics endpoint is not yet implemented. For now, use the /system endpoint to monitor system health and extract metrics from the response data.

# prometheus.yml - Alternative approach using /system endpoint
scrape_configs:
  - job_name: 'craneledger-api'
    static_configs:
      - targets: ['api.craneledger.ai:443']
    metrics_path: '/system'
    scheme: 'https'
    authorization:
      type: Bearer
      credentials: 'your_monitoring_token'
    # Note: This will return JSON, not Prometheus format
    # Use a custom exporter to convert JSON to Prometheus metrics

Application Monitoring Scripts

Python Monitoring Script

import requests
import time
from datetime import datetime

API_BASE = "https://api.craneledger.ai"
AUTH_HEADER = {"Authorization": "Bearer your_monitoring_token"}

def check_health():
    """Check basic health status"""
    try:
        response = requests.get(f"{API_BASE}/health", timeout=5)
        return response.status_code == 200 and response.text == "OK"
    except:
        return False

def get_system_metrics():
    """Get detailed system metrics"""
    try:
        response = requests.get(f"{API_BASE}/system", headers=AUTH_HEADER, timeout=10)
        return response.json()
    except:
        return None

def monitor_system():
    """Main monitoring loop"""
    while True:
        timestamp = datetime.now().isoformat()

        # Check health
        is_healthy = check_health()
        print(f"[{timestamp}] Health check: {'PASS' if is_healthy else 'FAIL'}")

        # Get system metrics
        metrics = get_system_metrics()
        if metrics:
            print(f"[{timestamp}] System status: {metrics['status']}")
            print(f"[{timestamp}] Events in last 24h: {metrics['event_stats']['events_last_24h']}")
            print(f"[{timestamp}] Database connections: {metrics['database']['active_connections']}")
        else:
            print(f"[{timestamp}] Failed to get system metrics")

        time.sleep(60)  # Check every minute

if __name__ == "__main__":
    monitor_system()

Shell Script for Basic Monitoring

#!/bin/bash

API_BASE="https://api.craneledger.ai"
AUTH_TOKEN="your_monitoring_token"

# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color

check_health() {
    local response=$(curl -s -w "%{http_code}" -o /dev/null "${API_BASE}/health")
    if [ "$response" = "200" ]; then
        echo -e "${GREEN}${NC} Health check passed"
        return 0
    else
        echo -e "${RED}${NC} Health check failed (HTTP $response)"
        return 1
    fi
}

check_system_status() {
    local response=$(curl -s -H "Authorization: Bearer ${AUTH_TOKEN}" "${API_BASE}/system")

    if [ $? -ne 0 ]; then
        echo -e "${RED}${NC} System check failed - connection error"
        return 1
    fi

    local status=$(echo "$response" | jq -r '.status' 2>/dev/null)
    local events_24h=$(echo "$response" | jq -r '.event_stats.events_last_24h' 2>/dev/null)

    case "$status" in
        "healthy")
            echo -e "${GREEN}${NC} System status: $status"
            ;;
        "degraded")
            echo -e "${YELLOW}${NC} System status: $status"
            ;;
        *)
            echo -e "${RED}${NC} System status: $status"
            ;;
    esac

    if [ "$events_24h" != "null" ]; then
        echo "Events in last 24h: $events_24h"
    fi
}

# Main monitoring loop
while true; do
    echo "=== Crane Ledger System Check $(date) ==="
    check_health
    check_system_status
    echo ""
    sleep 300  # Check every 5 minutes
done

API Rate Limits

The System API endpoints have special rate limit considerations:

EndpointRate LimitCreditsPurpose
/healthUnlimited0.00Designed for high-frequency health checks
/system60 requests/hour0.01Detailed system information

System Endpoint Authentication

The /system endpoint requires authentication and proper API key permissions. Use a dedicated monitoring API key with read-only permissions for security.


Error Responses

System endpoints may return the following errors:

Health Check Errors

  • 503 Service Unavailable: API is not responding
  • Connection timeout: Network or infrastructure issues

System Information Errors

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key provided",
    "status": 401
  }
}
{
  "error": {
    "code": "insufficient_permissions",
    "message": "API key does not have system monitoring permissions",
    "status": 403
  }
}

Need help?

Create a free account to access our support portal. Once signed in, use the Support tab in your dashboard to submit a support ticket — our team typically responds within 24 hours.