Oracle API Reference

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.

string

required

The diagnostic question or error description.

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.

string

required

Cluster identifier.

{
  "score": 87,
  "trend": "improving"
}

GET /api/clusters//issues

List active issues for a cluster.

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.

string

required

Cluster identifier.

string

required

Component to upgrade (e.g., k3s, rke2, longhorn).

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.

string

required

Cluster identifier.

string

required

The command to execute.

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
}

​Base URL

​AI Diagnostics

​POST /api/diagnose

​Advisories

​GET /api/advisories

​Clusters

​GET /api/clusters

​GET /api/clusters//health-score

​GET /api/clusters//issues

​Upgrade Risk

​POST /api/clusters//upgrade-risk

​CIS Benchmarks

​POST /api/cis/scan

​GPU Fleet

​GET /api/gpu/nodes

​Monitoring

​GET /api/monitoring/status

​GET /api/monitoring/metrics

​GET /api/monitoring/alerts

​etcd Management

​GET /api/etcd/snapshots

​POST /api/etcd/snapshot

​POST /api/etcd/restore

​Audit

​GET /api/audit/actions

​GET /api/audit/status

​GET /api/audit/k8s

​Support Bundle

​POST /api/support-bundle

​Operations

​POST /api/clusters//actions/execute

​Health & Status

​GET /health

​GET /api/llm/status

Base URL

AI Diagnostics

POST /api/diagnose

Advisories

GET /api/advisories

Clusters

GET /api/clusters

GET /api/clusters//health-score

GET /api/clusters//issues

Upgrade Risk

POST /api/clusters//upgrade-risk

CIS Benchmarks

POST /api/cis/scan

GPU Fleet

GET /api/gpu/nodes

Monitoring

GET /api/monitoring/status

GET /api/monitoring/metrics

GET /api/monitoring/alerts

etcd Management

GET /api/etcd/snapshots

POST /api/etcd/snapshot

POST /api/etcd/restore

Audit

GET /api/audit/actions

GET /api/audit/status

GET /api/audit/k8s

Support Bundle

POST /api/support-bundle

Operations

POST /api/clusters//actions/execute

Health & Status

GET /health

GET /api/llm/status