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
| Header | Required | Description |
|---|
Content-Type | Yes | application/json |
Authorization | No | Bearer <api-key> (if configured) |
Body
{
"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
{
"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 |
When generate_plan is false, the response omits fix_commands and returns only the analysis (root_cause, fix_summary, confidence).
