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

# General Settings — Dashboard API handoff (source-verified)

**Source of truth:** GitLab `main`: `modules/Settings/Routes/api.php`, `Interfaces/Http/Controllers/GeneralSettingsController.php`, `Interfaces/Http/Requests/UpdateGeneralSettingsRequest.php`, `Infrastructure/Settings/GeneralSettings.php`, `modules/Core/Interfaces/Http/Responses/ApiResponse.php`. **Base:** `/api/v1`.

This focused handoff documents the **two general-settings routes**. The full Settings module also has two localization admin routes, documented separately in `dashboard/settings.md`. Flutter can read general settings without authentication; updating settings is dashboard-only.

## GET `/api/v1/settings/general`

**Purpose:** Read platform-wide public settings, including whether registration is enabled. **Auth:** none. **Status:** 200. **Body:** none. **Query:** no documented parameters.

### Request field table

| Location | Field | Type | Required | Rule |
|---|---|---|---|---|
| Headers | `Accept` | string | Recommended | `application/json` |
| Body | — | — | No | Do not send a JSON object as a body |

### Response field table

| JSON path | Type | Nullable | Meaning |
|---|---|---|---|
| `data` | object | No | General settings (`GeneralSettings::toArray()`) |
| `data.site_name` | string | No | Site display name |
| `data.support_email` | string | No | Contact email |
| `data.registration_open` | boolean | No | Whether new registration is enabled |

**Illustrative HTTP 200:**

```json
{"data":{"site_name":"Outlet","support_email":"help@example.com","registration_open":true}}
```

**Dashboard UI:** Use these server values as the initial form state. Do not infer registration availability from local configuration.

## PATCH `/api/v1/settings/general`

**Purpose:** Partial update of general settings. **Auth:** `auth:sanctum` and permission `settings.manage`. **Status:** 200. **Content-Type:** `application/json`.

### Request field table

| JSON field | Type | Required | Backend validation | Behavior |
|---|---|---|---|---|
| `site_name` | string | No | `sometimes|string|max:120` | Replaces site name when supplied |
| `support_email` | string | No | `sometimes|email` | Replaces support email when supplied |
| `registration_open` | boolean | No | `sometimes|boolean` | Controls registration availability |

Only validated, supplied keys are applied; omitted keys retain their current values. The controller saves settings and returns the complete updated object. No documented request-level `reason`, `id`, or nested `settings` object.

**Illustrative request:**

```http
PATCH /api/v1/settings/general HTTP/1.1
Authorization: Bearer <dashboard-token>
Accept: application/json
Content-Type: application/json

{"site_name":"Outlet","registration_open":false}
```

### Response field table

| JSON path | Type | Nullable | Meaning |
|---|---|---|---|
| `data` | object | No | Full saved settings, not just changed fields |
| `data.site_name` | string | No | Updated or retained site name |
| `data.support_email` | string | No | Updated or retained support email |
| `data.registration_open` | boolean | No | Updated or retained registration switch |

**Illustrative HTTP 200:**

```json
{"data":{"site_name":"Outlet","support_email":"help@example.com","registration_open":false}}
```

### Error and integration handling

| Status | Condition | Dashboard action |
|---|---|---|
| 401 | Missing/invalid authentication | Require dashboard login |
| 403 | Actor lacks `settings.manage` | Hide/disable edit action and display permission error |
| 422 | Invalid field, e.g. overlong `site_name` or malformed email | Show field-level validation messages |

The global exception handler determines the exact error JSON envelope and localized message. **Do not treat the illustrative payloads as live captures.** No staging HTTP request or settings mutation was performed for this documentation.

### Source links

- [Settings routes](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Settings/Routes/api.php)
- [GeneralSettingsController](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Settings/Interfaces/Http/Controllers/GeneralSettingsController.php)
- [UpdateGeneralSettingsRequest](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Settings/Interfaces/Http/Requests/UpdateGeneralSettingsRequest.php)
- [GeneralSettings model](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Settings/Infrastructure/Settings/GeneralSettings.php)
