API Reference

Health Check

Returns API status and timestamp.

{
  "status": "operational",
  "timestamp": "2026-01-18T00:15:00Z"
}

Ingest

Ingest a Clotho audit report. This is the primary data intake endpoint.

Request Body

{
  "baseline_version": "1.0",
  "standard": "ISO 27002:2022",
  "generated_at": "2026-01-18T00:10:00Z",
  "nodes": ["athena"],
  "findings": [
    {
      "control_id": "8.20",
      "control_title": "Network Security",
      "node": "athena",
      "passed": false,
      "evidence": { "forbidden_ports": [23] }
    }
  ],
  "summary": {
    "total": 5,
    "passed": 4,
    "failed": 1
  }
}

Response

{
  "success": true,
  "auditId": "audit_20260118_001000",
  "entropy": 0.72
}

Threads (Stats)

Get MTBF and entropy statistics for all nodes.

{
  "nodes": [
    {
      "nodeId": "athena",
      "entropy": 0.72,
      "stability": 0.85,
      "mtbf_hours": 168,
      "last_audit": "2026-01-18T00:10:00Z"
    }
  ]
}

Get entropy timeline for a specific node.

{
  "nodeId": "athena",
  "timeline": [
    { "timestamp": "2026-01-17T00:00:00Z", "entropy": 0.15 },
    { "timestamp": "2026-01-18T00:00:00Z", "entropy": 0.72 }
  ]
}

Audits

List audit history for a node.

Get full audit details including all findings.

Delete an audit record.

Trends

Get trend data for a specific node (entropy over time, control pass rates).

Get global compliance trends across all nodes.

Comparison

Compare two audits to see what changed.

{
  "added_findings": [...],
  "removed_findings": [...],
  "changed_findings": [...],
  "entropy_delta": 0.57
}

Example: Full Workflow

# 1. Run Clotho audit
python clotho.py --node athena --format json

# 2. Ingest report
curl -X POST http://localhost:6380/api/ingest \
  -H "Content-Type: application/json" \
  -d @output/audit_20260118.json

# 3. Check stats
curl http://localhost:6380/api/threads/stats

# 4. View timeline
curl http://localhost:6380/api/threads/athena/timeline