> **Client contract note:** Apply [`shared/response-envelope.md`](../shared/response-envelope.md) to JSON responses after the response-contract release. Legacy wrapper examples below may reflect the prior API; the documented endpoint-specific payload fields are still useful. Not staging-verified.

# Reports — Dashboard API

Source: [`modules/Reports/Routes/api.php`](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Reports/Routes/api.php) (`main`). Paths shown relative to Laravel API prefix.

**Contract status:** route and middleware verified. Controller-level request schemas and exact success/error JSON have **not yet been verified**; examples are deliberately not fabricated.

## 1. `GET /admin/reports/settings`

**Purpose:** Report settings. **Access/middleware:** auth:sanctum; settings.manage.

| Contract item | Verified detail |
|---|---|
| Path parameters | None |
| Request headers | `Authorization: Bearer <token>` when `auth:sanctum` is required; `Accept: application/json` recommended |
| Query parameters | Not verified from controller |
| Request body and validation | Not verified from FormRequest/controller |
| Success response fields / JSON example | Not verified from presenter/resource |
| Error payload | Not verified from error handler |

## 2. `PATCH /admin/reports/settings`

**Purpose:** Update settings. **Access/middleware:** auth:sanctum; settings.manage.

| Contract item | Verified detail |
|---|---|
| Path parameters | None |
| Request headers | `Authorization: Bearer <token>` when `auth:sanctum` is required; `Accept: application/json` recommended |
| Query parameters | Not verified from controller |
| Request body and validation | Not verified from FormRequest/controller |
| Success response fields / JSON example | Not verified from presenter/resource |
| Error payload | Not verified from error handler |

## 3. `GET /admin/reports/settings/history`

**Purpose:** Settings history. **Access/middleware:** auth:sanctum; settings.manage.

| Contract item | Verified detail |
|---|---|
| Path parameters | None |
| Request headers | `Authorization: Bearer <token>` when `auth:sanctum` is required; `Accept: application/json` recommended |
| Query parameters | Not verified from controller |
| Request body and validation | Not verified from FormRequest/controller |
| Success response fields / JSON example | Not verified from presenter/resource |
| Error payload | Not verified from error handler |

## 4. `GET /admin/reports`

**Purpose:** Report list. **Access/middleware:** auth:sanctum; reports.view; throttle 120/min.

| Contract item | Verified detail |
|---|---|
| Path parameters | None |
| Request headers | `Authorization: Bearer <token>` when `auth:sanctum` is required; `Accept: application/json` recommended |
| Query parameters | Not verified from controller |
| Request body and validation | Not verified from FormRequest/controller |
| Success response fields / JSON example | Not verified from presenter/resource |
| Error payload | Not verified from error handler |

## 5. `GET /admin/reports/overview`

**Purpose:** Overview. **Access/middleware:** auth:sanctum; reports.view; throttle 120/min.

| Contract item | Verified detail |
|---|---|
| Path parameters | None |
| Request headers | `Authorization: Bearer <token>` when `auth:sanctum` is required; `Accept: application/json` recommended |
| Query parameters | Not verified from controller |
| Request body and validation | Not verified from FormRequest/controller |
| Success response fields / JSON example | Not verified from presenter/resource |
| Error payload | Not verified from error handler |

## 6. `GET /admin/reports/{key}`

**Purpose:** Report detail. **Access/middleware:** auth:sanctum; reports.view; throttle 120/min.

| Contract item | Verified detail |
|---|---|
| Path parameters | `key` |
| Request headers | `Authorization: Bearer <token>` when `auth:sanctum` is required; `Accept: application/json` recommended |
| Query parameters | Not verified from controller |
| Request body and validation | Not verified from FormRequest/controller |
| Success response fields / JSON example | Not verified from presenter/resource |
| Error payload | Not verified from error handler |

