API Reference

This section documents key API endpoints for advanced automation and configuration.

Base URL

All API requests should be prefixed with /api/v1.

Authentication

Requests must be authenticated using a Bearer Token (JWT) or an API Key (future).

Key Endpoints

Server Management

Reconfigure Proxy

Inject custom Traefik dynamic configuration.

• Endpoint: POST /api/v1/servers/{id}/reconfigure-proxy
• Body:

  {
    "traefik_custom_config": "yaml_string_here"
  }
  

Mesh Management

Get Mesh Config

Retrieve the WireGuard mesh configuration for the calling agent.

• Endpoint: GET /api/v1/mesh/config
• Headers: If-None-Match (Revision Etag)
• Response: Binary MeshState (bincode) or 304 Not Modified.

Push Mesh Status

Report the local mesh health and peer status to the control plane.

• Endpoint: POST /api/v1/mesh/status
• Body: JSON object containing local peer info.

Resource Management

Backup Configuration

Manage backup schedules and policies.

• Endpoint: POST /api/v1/resources/{id}/backup-config
• Body:

  {
    "strategy": "postgres",
    "frequency_cron": "0 0 * * *",
    "retention_days": 14,
    "enabled": true,
    "storage_provider_id": "uuid"
  }
  

Metrics & Observability

• Endpoint: POST /api/v1/metrics/ingest
• Body:

  {
    "host": { "cpu_percent": 12.5, "memory_used_bytes": 1024000, "...": "..." },
    "containers": [
      { "name": "/webapp", "cpu_percent": 2.1, "labels": { "act.service": "uuid" } }
    ],
    "mesh": { "active_peers": 5, "peer_health": [] },
    "samples": [
      { "metric_type": "http_latency_avg_ns", "value": 4500000, "labels": {} }
    ],
    "capabilities": { "ebpf_available": true },
    "agent_overhead": { "cpu_permille": 3, "memory_rss_bytes": 4500000 }
  }
  

Query Metrics

Query metrics for visualization.

• Endpoint: GET /api/v1/metrics/query
• Params: resource_id, start, end, step

Authentication & Recovery

Get Recovery Kit

Retrieve the emergency recovery kit (Master Key, Admin Token).

• Endpoint: GET /api/v1/auth/recovery-kit
• Requires: Admin privileges