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
/healthReturns 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
/systemReturns 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
| Field | Type | Description |
|---|---|---|
version | string | API version number |
status | string | Overall system status (healthy, degraded, maintenance) |
uptime | string | How long the system has been running |
timestamp | string | Current server timestamp |
event_stats | object | Comprehensive event system statistics |
database | object | Database connection and performance metrics |
workers | object | Background worker system status |
cache | object | Caching system performance metrics |
Event Statistics Details
The event_stats object provides detailed information about the event system:
| Field | Description |
|---|---|
total_events | Total number of events in the system |
events_last_24h | Events created in the last 24 hours |
events_by_type | Breakdown of events by type |
recent_events | Last 10 events with basic information |
System Status Values
| Status | Description | Action Required |
|---|---|---|
healthy | All systems operational | None |
degraded | Some systems experiencing issues | Monitor closely |
maintenance | System under maintenance | API 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:
| Endpoint | Rate Limit | Credits | Purpose |
|---|---|---|---|
/health | Unlimited | 0.00 | Designed for high-frequency health checks |
/system | 60 requests/hour | 0.01 | Detailed 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.
- ✨ For LLMs/AI assistants: Read our structured API reference