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

# Feature Flags — Flutter source-reviewed API contract

**Base URL:** `/api/v1`. **Accept:** `application/json`. Examples are illustrative values with source-verified field names, not captured runtime traffic. Validation errors are normally 422; do not assume a particular global error envelope without runtime verification.

**Source:** [api.php](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/FeatureFlags/Routes/api.php), [FeatureController.php](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/FeatureFlags/Interfaces/Http/Controllers/FeatureController.php). Reviewed against `main` on 2026-11-22.

## `GET /api/v1/features`

| Aspect | Contract |
|---|---|
| Auth | `Authorization: Bearer <token>`; Sanctum required |
| Request | No query, path parameters, or JSON body |
| Success | `200 OK` |
| Screen mapping | Bootstrap feature toggles; hide/show gated features based on values returned for the **current signed-in actor** |

**Example request**
```http
GET /api/v1/features HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
```

**200 response — illustrative flag names, not guaranteed keys**
```json
{"data":{"example_feature":true,"another_example":false}}
```

| JSON path | Type | Semantics |
|---|---|---|
| `data` | `object<string, boolean>` | Keys are names from `Feature::defined()`; values are `Feature::for(request.user).active(name)` |
| `data.<flag_name>` | `boolean` | Actor-resolved activation; keys are dynamic, not a fixed enum |

**Errors:** `401` for missing/invalid auth. No permission middleware beyond authentication. **Important:** Never assume example flag names exist; render only flags supplied by the API. The route does not expose a dashboard write endpoint.
