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

# Core — Outlet API handoff (flutter)

> **Verification boundary:** The detailed contract below was derived from repository source, not from live HTTP captures. Fields explicitly marked unverified remain open. The earlier route inventory is retained below for cross-checking; where it says “not verified”, the more recent source-reviewed contract takes precedence.

## Controller-reviewed contracts


All URLs relative to `/api/v1/`. Example values are **illustrative**, not captured from a live server. Angle-bracket text means a placeholder, not a literal API value. Error statuses are listed only when supported by controller code.

**Coverage in this document:** 3 endpoints; this is NOT an assertion that the entire module is complete.

## `GET /api/v1/health/live`

**Purpose:** Liveness probe: HTTP process responds.
**Access:** Public

| Request field | Type | Required | Validation |
|---|---|---|---|
| — | — | — | No request fields |

**Example request:**

```http
GET /api/v1/health/live
Content-Type: application/json

{}
```

**Example success response — HTTP 200:**

```json
{
  "status": "ok"
}
```

**Response field types:**

| Field | Type |
|---|---|
| `status` | string |

**Notes / errors:** Direct JSON response; NOT wrapped in data.

**Source:** [Core/Interfaces/Http/Controllers/HealthController.php](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Core/Interfaces/Http/Controllers/HealthController.php)

---

## `GET /api/v1/health/ready`

**Purpose:** Readiness probe: database and cache connectivity.
**Access:** Public

| Request field | Type | Required | Validation |
|---|---|---|---|
| — | — | — | No request fields |

**Example request:**

```http
GET /api/v1/health/ready
Content-Type: application/json

{}
```

**Example success response — HTTP 200:**

```json
{
  "status": "ok",
  "checks": {
    "database": "ok",
    "cache": "ok"
  }
}
```

**Response field types:**

| Field | Type |
|---|---|
| `status` | string |
| `checks.database` | string |
| `checks.cache` | string |

**Notes / errors:** On any failed dependency HTTP 503 with status=degraded and corresponding check=fail. Direct JSON, not data wrapper.

**Source:** [Core/Interfaces/Http/Controllers/HealthController.php](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Core/Interfaces/Http/Controllers/HealthController.php)

---

## `GET /api/v1/locales`

**Purpose:** Enabled locales for language selector; default first.
**Access:** Public

| Request field | Type | Required | Validation |
|---|---|---|---|
| — | — | — | No request fields |

**Example request:**

```http
GET /api/v1/locales
Content-Type: application/json

{}
```

**Example success response — HTTP 200:**

```json
{
  "data": [
    {
      "code": "ar",
      "native_name": "العربية",
      "dir": "rtl",
      "default": true
    },
    {
      "code": "en",
      "native_name": "English",
      "dir": "ltr",
      "default": false
    }
  ]
}
```

**Response field types:**

| Field | Type |
|---|---|
| `data` | array |
| `data[].code` | string |
| `data[].native_name` | string |
| `data[].dir` | string |
| `data[].default` | boolean |

**Notes / errors:** Locale list and default depend on settings. Example languages are illustrative.

**Source:** [Core/Interfaces/Http/Controllers/LocalesController.php](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Core/Interfaces/Http/Controllers/LocalesController.php)

---


---

## Earlier route inventory (historical; superseded by contracts above)

# Core — Flutter API

Source: [`modules/Core/Routes/api.php`](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Core/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 /health/live`

**Purpose:** Liveness. **Access/middleware:** public.

| 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. `GET /health/ready`

**Purpose:** Readiness. **Access/middleware:** public.

| 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 /locales`

**Purpose:** Enabled languages and direction. **Access/middleware:** public.

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

