System Status API

API service for checking system status including running Docker containers and systemd services.

Base URL: api.koveh.com/system/

Endpoints

Method	Endpoint	Description	Authentication
GET	`/health`	Service health check	None
GET	`/status`	Get system status (Docker containers and systemd services)	Required (except localhost)

Authentication

The /status endpoint requires authentication for external requests:

Localhost access: No authentication required (127.0.0.1, localhost, private IPs)
External access: Requires Bearer token authentication with API key from api_users table

Authentication Header

Authorization: Bearer YOUR_API_KEY

Local Access

Local requests (from localhost or private networks) don't require authentication:

curl http://localhost:8060/status

External Access

External requests require a valid API key:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.koveh.com/system/status"

System Status

Get system status including running Docker containers and systemd services.

Endpoint: GET /status

Response

{
  "docker_containers": [
    {
      "container_id": "8c6f62524336",
      "image": "koveh-web",
      "command": "\"docker-entrypoint.s…\"",
      "created": "2025-11-04 05:26:59 +0300 MSK",
      "status": "Up 2 days (healthy)",
      "ports": "0.0.0.0:3000->3000/tcp, [::]:3000->3000/tcp",
      "names": "koveh-web-1"
    }
  ],
  "systemd_services": [
    {
      "unit": "admin-stats-api.service",
      "load": "loaded",
      "active": "active",
      "sub": "running",
      "description": "Admin Statistics API"
    }
  ]
}

Response Fields

Docker Containers

container_id (string): Short container ID
image (string): Docker image name
command (string): Container command
created (string): Container creation timestamp
status (string): Container status (e.g., "Up 2 days (healthy)")
ports (string): Port mappings
names (string): Container name

Systemd Services

unit (string): Service unit name
load (string): Load state (e.g., "loaded")
active (string): Active state (e.g., "active")
sub (string): Sub state (e.g., "running")
description (string): Service description

Example Request

# Local access (no auth)
curl http://localhost:8060/status

# External access (with auth)
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.koveh.com/system/status"

Example Response

{
  "docker_containers": [
    {
      "container_id": "8c6f62524336",
      "image": "koveh-web",
      "command": "\"docker-entrypoint.s…\"",
      "created": "2025-11-04 05:26:59 +0300 MSK",
      "status": "Up 2 days (healthy)",
      "ports": "0.0.0.0:3000->3000/tcp",
      "names": "koveh-web-1"
    },
    {
      "container_id": "12ef370b60b1",
      "image": "koveh-github-web",
      "command": "\"docker-entrypoint.s…\"",
      "created": "2025-10-29 14:16:01 +0300 MSK",
      "status": "Up 15 seconds (health: starting)",
      "ports": "0.0.0.0:3999->3000/tcp",
      "names": "koveh-com-github"
    }
  ],
  "systemd_services": [
    {
      "unit": "admin-stats-api.service",
      "load": "loaded",
      "active": "active",
      "sub": "running",
      "description": "Admin Statistics API"
    },
    {
      "unit": "ai_api.service",
      "load": "loaded",
      "active": "active",
      "sub": "running",
      "description": "AI API Service"
    }
  ]
}

Health Check

Check service health status.

Endpoint: GET /health

Response

{
  "status": "healthy"
}

Example Request

curl https://api.koveh.com/system/health

Integration Examples

Python Example

import requests

def get_system_status(api_key=None):
    headers = {}
    if api_key:
        headers["Authorization"] = f"Bearer {api_key}"
    
    response = requests.get(
        "https://api.koveh.com/system/status",
        headers=headers
    )
    return response.json()

# Get system status with API key
status = get_system_status(api_key="YOUR_API_KEY")
print(f"Docker containers: {len(status['docker_containers'])}")
print(f"Systemd services: {len(status['systemd_services'])}")

# List all running containers
for container in status['docker_containers']:
    print(f"{container['names']}: {container['status']}")

# List all running services
for service in status['systemd_services']:
    print(f"{service['unit']}: {service['active']}")

JavaScript Example

async function getSystemStatus(apiKey = null) {
    const headers = {};
    if (apiKey) {
        headers['Authorization'] = `Bearer ${apiKey}`;
    }
    
    const response = await fetch('https://api.koveh.com/system/status', {
        headers: headers
    });
    return await response.json();
}

// Get system status
getSystemStatus('YOUR_API_KEY')
    .then(status => {
        console.log(`Docker containers: ${status.docker_containers.length}`);
        console.log(`Systemd services: ${status.systemd_services.length}`);
        
        // List all running containers
        status.docker_containers.forEach(container => {
            console.log(`${container.names}: ${container.status}`);
        });
        
        // List all running services
        status.systemd_services.forEach(service => {
            console.log(`${service.unit}: ${service.active}`);
        });
    });

Bash Example

#!/bin/bash

API_KEY="YOUR_API_KEY"
BASE_URL="https://api.koveh.com/system"

# Get system status
response=$(curl -s -H "Authorization: Bearer $API_KEY" "$BASE_URL/status")

# Parse and display
echo "Docker Containers:"
echo "$response" | jq -r '.docker_containers[] | "\(.names): \(.status)"'

echo ""
echo "Systemd Services:"
echo "$response" | jq -r '.systemd_services[] | "\(.unit): \(.active)"'

Error Handling

The API returns standard error responses:

Unauthorized (401)

{
  "detail": "API key required"
}

{
  "detail": "Invalid API key"
}

Internal Server Error (500)

{
  "detail": "Database error"
}

Common error codes:

401: Unauthorized (missing or invalid API key)
500: Internal Server Error (database or system error)

Security

Local Access: Requests from localhost (127.0.0.1, localhost, ::1) or private networks (192.168.x.x, 10.x.x.x) don't require authentication
External Access: All external requests require a valid API key from the api_users table
API Key Validation: API keys are validated against the PostgreSQL database
Health Endpoint: The /health endpoint is publicly accessible (no authentication required)

Use Cases

System Monitoring: Monitor running Docker containers and systemd services
Infrastructure Management: Track system status and service health
DevOps Automation: Integrate system status checks into CI/CD pipelines
Dashboard Integration: Display system status in monitoring dashboards
Alerting: Use system status data for alerting and notifications

Architecture

graph TD
    A[Client] --> B[api.koveh.com/system]
    B --> C[System Status API]
    C --> D[Authentication Check]
    D -->|Local| E[Allow Access]
    D -->|External| F[Verify API Key]
    F -->|Valid| E
    F -->|Invalid| G[401 Unauthorized]
    E --> H[Docker ps]
    E --> I[systemctl list-units]
    H --> J[Running Containers]
    I --> K[Running Services]
    J --> L[JSON Response]
    K --> L

Service Details

Port: 8060
Framework: FastAPI
Database: PostgreSQL (for API key validation)
Deployment: Systemd service
Location: /root/api/system/
Virtual Environment: /root/api/system/venv/

System Status API

On this page