Skip to main content
The Pastures Engine exposes a REST API that the extension calls for AI diagnostics, cluster management, and operational data. All endpoints accept and return JSON. Bearer token authentication is optional and configured in Settings.

​
Base URL

The Engine base URL is configured in the Pastures extension settings page. All endpoints below are relative to this base URL.

​
AI Diagnostics

​
POST /api/diagnose

Generate an AI diagnosis for a cluster issue.
​
query
string
required
The diagnostic question or error description.
​
generate_plan
boolean
default:false
Whether to generate a remediation plan with fix commands.
{
  "diagnosis": {
    "root_cause": "etcd cluster has lost quorum due to a single-member configuration",
    "fix_summary": "Add two additional etcd members to restore HA quorum",
    "fix_commands": [
      {
        "command": "etcdctl member add etcd-1 --peer-urls=https://10.0.1.2:2380",
        "description": "Add first new etcd member"
      },
      {
        "command": "etcdctl member add etcd-2 --peer-urls=https://10.0.1.3:2380",
        "description": "Add second new etcd member"
      }
    ],
    "confidence": 0.92,
    "source_url": "https://github.com/k3s-io/k3s/issues/8921",
    "warnings": [
      "Ensure etcd data directory backup exists before adding members"
    ],
    "diagnosis_id": "diag_abc123"
  }
}

​
Advisories

​
GET /api/advisories

List active advisories for the current cluster. 
{
  "advisories": [
    {
      "id": "adv-001",
      "severity": "critical",
      "title": "etcd cluster has only 1 member (no HA)",
      "relevance": 0.95,
      "recommended_action": "Add etcd members to restore quorum",
      "created_at": "2026-04-20T14:30:00Z"
    }
  ]
}

​
Clusters

​
GET /api/clusters

List all registered clusters. 
[
  {
    "cluster_id": "c-m-abc123",
    "cluster_name": "prod-east",
    "health_status": "healthy",
    "k8s_version": "v1.31.4+k3s1",
    "node_count": 5,
    "provider": "k3s"
  }
]

​
GET /api/clusters//health-score

Get the health score for a specific cluster.
​
id
string
required
Cluster identifier.
{
  "score": 87,
  "trend": "improving"
}

​
GET /api/clusters//issues

List active issues for a cluster.
​
id
string
required
Cluster identifier.
{
  "issues": [
    {
      "id": "issue-001",
      "severity": "warning",
      "title": "Longhorn replica count below desired",
      "detected_at": "2026-04-24T09:15:00Z"
    }
  ]
}

​
Upgrade Risk

​
POST /api/clusters//upgrade-risk

Assess risk for a component upgrade.
​
id
string
required
Cluster identifier.
​
component
string
required
Component to upgrade (e.g., k3s, rke2, longhorn).
​
target_version
string
required
Target version string.
{
  "risk_level": "medium",
  "known_issues": 3,
  "breaking_changes": 1,
  "recommendation": "Review breaking changes before proceeding"
}

​
CIS Benchmarks

​
POST /api/cis/scan

Trigger a CIS benchmark scan on the cluster. 
{
  "scan_id": "scan-456",
  "status": "running",
  "started_at": "2026-04-25T10:00:00Z"
}

​
GPU Fleet

​
GET /api/gpu/nodes

List GPU nodes across the fleet. 
[
  {
    "node_name": "gpu-worker-01",
    "cluster": "prod-east",
    "gpu_model": "NVIDIA A100",
    "gpu_count": 4,
    "utilization": 0.82,
    "memory_used_gb": 62.4,
    "memory_total_gb": 80
  }
]

​
Monitoring

​
GET /api/monitoring/status

Get monitoring subsystem status.

​
GET /api/monitoring/metrics

Get cluster metrics data.

​
GET /api/monitoring/alerts

List active monitoring alerts. 
{
  "alerts": [
    {
      "id": "alert-789",
      "severity": "warning",
      "name": "NodeMemoryPressure",
      "message": "Node worker-03 memory usage above 90%",
      "firing_since": "2026-04-25T08:30:00Z"
    }
  ]
}

​
etcd Management

​
GET /api/etcd/snapshots

List available etcd snapshots.

​
POST /api/etcd/snapshot

Create a new etcd snapshot.

​
POST /api/etcd/restore

Restore from an etcd snapshot. 
{
  "restore_id": "restore-012",
  "status": "in_progress",
  "snapshot_name": "etcd-snapshot-2026-04-24",
  "started_at": "2026-04-25T11:00:00Z"
}

​
Audit

​
GET /api/audit/actions

List audited actions.

​
GET /api/audit/status

Get audit subsystem status.

​
GET /api/audit/k8s

Get Kubernetes audit events.

​
Support Bundle

​
POST /api/support-bundle

Generate a support bundle for troubleshooting. 
{
  "bundle_id": "bundle-345",
  "status": "generating",
  "estimated_size_mb": 45
}

​
Operations

​
POST /api/clusters//actions/execute

Execute a fix command on a cluster.
​
id
string
required
Cluster identifier.
​
command
string
required
The command to execute.
​
diagnosis_id
string
Associated diagnosis ID for traceability.
{
  "execution_id": "exec-678",
  "status": "completed",
  "output": "member added successfully"
}

​
Health & Status

​
GET /health

Engine health check. 
{
  "status": "ok",
  "version": "1.4.2",
  "uptime_seconds": 86400
}

​
GET /api/llm/status

AI provider connection status. 
{
  "provider": "oracle",
  "status": "connected",
  "model": "oracle-k8s-v2",
  "corpus_size": 48412
}