> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pastures.farm/llms.txt
> Use this file to discover all available pages before exploring further.

# Oracle API Reference

> REST API endpoints for the Pastures Engine that powers Rancher Oracle.

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.

<ParamField body="query" type="string" required>
  The diagnostic question or error description.
</ParamField>

<ParamField body="generate_plan" type="boolean" default={false}>
  Whether to generate a remediation plan with fix commands.
</ParamField>

<ResponseExample>
  ```json theme={null}
  {
    "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"
    }
  }
  ```
</ResponseExample>

***

## Advisories

### GET /api/advisories

List active advisories for the current cluster.

<ResponseExample>
  ```json theme={null}
  {
    "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"
      }
    ]
  }
  ```
</ResponseExample>

***

## Clusters

### GET /api/clusters

List all registered clusters.

<ResponseExample>
  ```json theme={null}
  [
    {
      "cluster_id": "c-m-abc123",
      "cluster_name": "prod-east",
      "health_status": "healthy",
      "k8s_version": "v1.31.4+k3s1",
      "node_count": 5,
      "provider": "k3s"
    }
  ]
  ```
</ResponseExample>

### GET /api/clusters/{id}/health-score

Get the health score for a specific cluster.

<ParamField path="id" type="string" required>
  Cluster identifier.
</ParamField>

<ResponseExample>
  ```json theme={null}
  {
    "score": 87,
    "trend": "improving"
  }
  ```
</ResponseExample>

### GET /api/clusters/{id}/issues

List active issues for a cluster.

<ParamField path="id" type="string" required>
  Cluster identifier.
</ParamField>

<ResponseExample>
  ```json theme={null}
  {
    "issues": [
      {
        "id": "issue-001",
        "severity": "warning",
        "title": "Longhorn replica count below desired",
        "detected_at": "2026-04-24T09:15:00Z"
      }
    ]
  }
  ```
</ResponseExample>

***

## Upgrade Risk

### POST /api/clusters/{id}/upgrade-risk

Assess risk for a component upgrade.

<ParamField path="id" type="string" required>
  Cluster identifier.
</ParamField>

<ParamField body="component" type="string" required>
  Component to upgrade (e.g., `k3s`, `rke2`, `longhorn`).
</ParamField>

<ParamField body="target_version" type="string" required>
  Target version string.
</ParamField>

<ResponseExample>
  ```json theme={null}
  {
    "risk_level": "medium",
    "known_issues": 3,
    "breaking_changes": 1,
    "recommendation": "Review breaking changes before proceeding"
  }
  ```
</ResponseExample>

***

## CIS Benchmarks

### POST /api/cis/scan

Trigger a CIS benchmark scan on the cluster.

<ResponseExample>
  ```json theme={null}
  {
    "scan_id": "scan-456",
    "status": "running",
    "started_at": "2026-04-25T10:00:00Z"
  }
  ```
</ResponseExample>

***

## GPU Fleet

### GET /api/gpu/nodes

List GPU nodes across the fleet.

<ResponseExample>
  ```json theme={null}
  [
    {
      "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
    }
  ]
  ```
</ResponseExample>

***

## 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.

<ResponseExample>
  ```json theme={null}
  {
    "alerts": [
      {
        "id": "alert-789",
        "severity": "warning",
        "name": "NodeMemoryPressure",
        "message": "Node worker-03 memory usage above 90%",
        "firing_since": "2026-04-25T08:30:00Z"
      }
    ]
  }
  ```
</ResponseExample>

***

## 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.

<ResponseExample>
  ```json theme={null}
  {
    "restore_id": "restore-012",
    "status": "in_progress",
    "snapshot_name": "etcd-snapshot-2026-04-24",
    "started_at": "2026-04-25T11:00:00Z"
  }
  ```
</ResponseExample>

***

## 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.

<ResponseExample>
  ```json theme={null}
  {
    "bundle_id": "bundle-345",
    "status": "generating",
    "estimated_size_mb": 45
  }
  ```
</ResponseExample>

***

## Operations

### POST /api/clusters/{id}/actions/execute

Execute a fix command on a cluster.

<ParamField path="id" type="string" required>
  Cluster identifier.
</ParamField>

<ParamField body="command" type="string" required>
  The command to execute.
</ParamField>

<ParamField body="diagnosis_id" type="string">
  Associated diagnosis ID for traceability.
</ParamField>

<ResponseExample>
  ```json theme={null}
  {
    "execution_id": "exec-678",
    "status": "completed",
    "output": "member added successfully"
  }
  ```
</ResponseExample>

***

## Health & Status

### GET /health

Engine health check.

<ResponseExample>
  ```json theme={null}
  {
    "status": "ok",
    "version": "1.4.2",
    "uptime_seconds": 86400
  }
  ```
</ResponseExample>

### GET /api/llm/status

AI provider connection status.

<ResponseExample>
  ```json theme={null}
  {
    "provider": "oracle",
    "status": "connected",
    "model": "oracle-k8s-v2",
    "corpus_size": 48412
  }
  ```
</ResponseExample>