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

# API Reference Overview

> Introduction to the Pastures Engine REST API consumed by the extension.

## Overview

The Pastures Engine exposes a REST API that the Rancher extension consumes. All endpoints accept and return **JSON** (`Content-Type: application/json`).

## Authentication

Authentication is optional and configured per-installation in **Pastures → Settings**.

When an API key is set, every request includes an `Authorization` header:

```
Authorization: Bearer <api-key>
```

If no key is configured, requests are sent without the header.

## Base URL

The Engine URL is stored in `localStorage` and configurable in **Settings**. All API paths in this reference are relative to that base URL.

## Endpoint Groups

<CardGroup cols={2}>
  <Card title="Diagnostics" icon="stethoscope" href="/api-reference/diagnose">
    `POST /api/diagnose` — AI-powered root-cause analysis and remediation plans.
  </Card>

  <Card title="Advisories" icon="triangle-exclamation" href="/api-reference/advisories">
    `GET /api/advisories` — Security and operational advisories relevant to the cluster.
  </Card>

  <Card title="Health & Status" icon="heart-pulse" href="/api-reference/health">
    `GET /health` and `GET /api/llm/status` — Engine health check and AI provider status.
  </Card>

  <Card title="Clusters" icon="server">
    `GET /api/clusters/*` — Cluster inventory, status, and metadata.
  </Card>

  <Card title="Operations" icon="wrench">
    `/api/cis/*`, `/api/etcd/*`, `/api/monitoring/*`, `/api/audit/*` — CIS benchmarks, etcd health, monitoring, and audit logs.
  </Card>

  <Card title="GPU" icon="microchip">
    `/api/gpu/*` — GPU inventory, utilization, and scheduling.
  </Card>

  <Card title="Support" icon="life-ring">
    `POST /api/support-bundle` — Generate and download support bundles.
  </Card>

  <Card title="Actions" icon="bolt">
    `POST /api/clusters/{id}/actions/execute` — Execute remediation actions on a cluster.
  </Card>
</CardGroup>

## Demo Mode

When demo mode is enabled in the extension, `engineFetch()` short-circuits and returns synthetic data from `lib/demoResponses.ts` without making any network calls. This allows the full UI to function without a running Engine instance.

## Error Handling

The Engine returns standard HTTP status codes:

| Status | Meaning                                             |
| ------ | --------------------------------------------------- |
| `200`  | Success                                             |
| `400`  | Bad request — invalid or missing parameters         |
| `401`  | Unauthorized — invalid or missing API key           |
| `404`  | Endpoint not found                                  |
| `500`  | Internal server error                               |
| `503`  | Service unavailable — Engine or AI provider is down |

Error responses include a JSON body:

```json theme={null}
{
  "error": "Description of what went wrong"
}
```