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

# Diagnose Endpoint

> AI-powered root-cause analysis and remediation plans.

## `POST /api/diagnose`

Submits a natural-language query to the Pastures Engine for AI-powered diagnosis. The Engine analyzes the cluster state, documentation corpus, and advisory history to produce a root-cause analysis with actionable fix commands.

The extension calls this endpoint from `PasturesAIDrawer` when a user asks a question.

## Request

### Headers

| Header          | Required | Description                        |
| --------------- | -------- | ---------------------------------- |
| `Content-Type`  | Yes      | `application/json`                 |
| `Authorization` | No       | `Bearer <api-key>` (if configured) |

### Body

```json theme={null}
{
  "query": "Why are pods in CrashLoopBackOff in the monitoring namespace?",
  "generate_plan": true
}
```

| Field           | Type      | Description                                                 |
| --------------- | --------- | ----------------------------------------------------------- |
| `query`         | `string`  | Natural-language question about the cluster.                |
| `generate_plan` | `boolean` | When `true`, the response includes executable fix commands. |

## Response

```json theme={null}
{
  "diagnosis": {
    "root_cause": "The Prometheus pod is exceeding its memory limit (2Gi) due to high cardinality metrics from a misconfigured ServiceMonitor targeting all namespaces.",
    "fix_summary": "Restrict the ServiceMonitor selector to the monitoring namespace and increase the Prometheus memory limit to 4Gi.",
    "fix_commands": [
      {
        "command": "kubectl patch servicemonitor/cluster-wide -n monitoring --type=merge -p '{\"spec\":{\"namespaceSelector\":{\"matchNames\":[\"monitoring\"]}}}'",
        "description": "Restrict ServiceMonitor to monitoring namespace"
      },
      {
        "command": "kubectl patch prometheus/k8s -n monitoring --type=merge -p '{\"spec\":{\"resources\":{\"limits\":{\"memory\":\"4Gi\"}}}}'",
        "description": "Increase Prometheus memory limit to 4Gi"
      }
    ],
    "confidence": 0.92,
    "source_url": "https://prometheus.io/docs/prometheus/latest/configuration/configuration/#servicemonitor",
    "warnings": [
      "Restricting the namespace selector will stop monitoring other namespaces"
    ],
    "diagnosis_id": "diag-a1b2c3d4"
  }
}
```

### Response Fields

| Field          | Type       | Description                                                                      |
| -------------- | ---------- | -------------------------------------------------------------------------------- |
| `root_cause`   | `string`   | Explanation of the identified problem.                                           |
| `fix_summary`  | `string`   | Human-readable summary of the recommended fix.                                   |
| `fix_commands` | `array`    | Ordered list of commands to execute. Each entry has `command` and `description`. |
| `confidence`   | `number`   | Confidence score from 0 to 1.                                                    |
| `source_url`   | `string`   | Reference documentation link.                                                    |
| `warnings`     | `string[]` | Potential side effects of the fix.                                               |
| `diagnosis_id` | `string`   | Unique identifier for this diagnosis (used for audit logging).                   |

## Confidence and Risk Levels

The extension maps the `confidence` score to a risk level that determines UI behavior and confirmation requirements:

| Confidence | Risk Level | UI Behavior                                                       |
| ---------- | ---------- | ----------------------------------------------------------------- |
| ≥ 0.85     | **LOW**    | Green indicator; single-click execution available                 |
| ≥ 0.70     | **MEDIUM** | Yellow indicator; confirmation dialog required                    |
| \< 0.70    | **HIGH**   | Red indicator; detailed review and explicit confirmation required |

<Info>
  When `generate_plan` is `false`, the response omits `fix_commands` and returns only the analysis (`root_cause`, `fix_summary`, `confidence`).
</Info>