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

# Pages — 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


**Source:** GitLab `alalmiyalhura/outlet`, branch `main`, `modules/Pages/Routes/api.php`, controllers, `PageContentRequest.php`, `Presenter.php`, `RevisionDiff.php`, `PageService.php`.

**Scope:** 15 distinct operations: one public route and 14 dashboard operations. Each dashboard operation is exposed under both `/admin/pages` and legacy `/pages` (28 dashboard route variants, plus one public route). All paths below are relative to `/api/v1`. The legacy alias has the identical method, request and response.

**Response convention:** `ApiResponse::ok/created` returns a `data` envelope (as shown by other controllers); exact common error-envelope shape should be checked against Core `ApiResponse` and exception handlers before declaring live contract validation. JSON values below are **illustrative**; not captured from running server.

**Security:** Public GET requires no login and is throttled to 120/min. All editor routes require `auth:sanctum` + `pages.manage`. Approve/send-back/unpublish require `auth:sanctum` + `pages.publish`. Authorization failure is typically 403; authentication failure typically 401; validation failure typically 422. These status codes are framework expectations, not live-tested assertions.

**Common page response fields:** `id` integer, `slug` string, `locale` string, `published` nullable revision object, `working` nullable revision object. A revision contains `number` integer, `status` string, `title` string, `body` string, `meta_title` nullable string, `meta_description` nullable string, `author_id` integer, `submitted_by` nullable integer, `submitted_at` nullable ISO date-time, `reviewed_by` nullable integer, `reviewed_at` nullable ISO date-time, `review_comment` nullable string, `publish_at` nullable ISO date-time, `published_at` nullable ISO date-time. `published` and `working` can vary according to workflow state.

**Examples use placeholder values.** `GET /admin/pages` response summary properties and public published-page projection are not fully established by the controllers alone; the examples are deliberately labeled partial, not claimed complete.


## 1. `GET /api/v1/content/{slug}`

**Purpose:** Read the published page by slug; draft content is never exposed.

**Screen:** Flutter + public website. **Authorization:** Public.

**Request contract (field names, types, constraints):** slug: string path, `[a-z0-9\-/]+`; `locale`: optional enabled locale query; `If-None-Match`: optional HTTP header.

**Example request:**

No JSON request body.


**Example response:**

```json
{
  "data": {
    "slug": "about-us",
    "locale": "ar",
    "revision": 2,
    "title": "من نحن",
    "body": "<p>نبذة عن المنصة</p>",
    "meta_title": "من نحن",
    "meta_description": "تعرف على المنصة"
  }
}
```


**Response interpretation:** 200; 304 when ETag matches (no content); 404 if no published locale variant.

HTTP response headers include `ETag`, `Cache-Control`, `Vary: Accept-Language`. `If-None-Match` matching the ETag yields 304. Locale fallback: enabled query locale → request locale → platform default. Published-page field list should be verified in `PublishedPages` implementation.


## 2. `GET /api/v1/admin/pages`

**Purpose:** List page summaries, optionally filtered.

**Screen:** Dashboard / pages list. **Authorization:** Bearer token + `pages.manage`.

**Request contract (field names, types, constraints):** `status`: optional enum draft|in_review|approved|published|archived; `locale`: optional string max 8; `q`: optional string max 100.

**Example request:**

No JSON request body.


**Example response:**

```json
{
  "data": [
    {
      "id": 12,
      "slug": "about-us",
      "locale": "ar"
    }
  ]
}
```


**Response interpretation:** 200; summary item shape requires repository read-model confirmation.

**Unverified field details:** `PageRepository::summaries()` determines exact summary fields; do not treat example as exhaustive.


## 3. `POST /api/v1/admin/pages`

**Purpose:** Create a page and initial draft revision.

**Screen:** Dashboard / new page. **Authorization:** Bearer token + `pages.manage`.

**Request contract (field names, types, constraints):** `slug`: required string max 150; `locale`: required enabled locale string max 8; `title`: required string max 200; `body`: present, nullable string max 500000; `meta_title`: nullable string max 70; `meta_description`: nullable string max 200; `base_revision`: prohibited.

**Example request:**

```json
{
  "slug": "about-us",
  "locale": "ar",
  "title": "من نحن",
  "body": "<p>نبذة عن المنصة</p>",
  "meta_title": "من نحن",
  "meta_description": "تعرف على المنصة"
}
```


**Example response:**

```json
{
  "data": {
    "id": 12,
    "slug": "about-us",
    "locale": "ar",
    "published": null,
    "working": {
      "number": 1,
      "status": "draft",
      "title": "من نحن",
      "body": "<p>نبذة عن المنصة</p>",
      "meta_title": "من نحن",
      "meta_description": "تعرف على المنصة",
      "author_id": 3,
      "submitted_by": null,
      "submitted_at": null,
      "reviewed_by": null,
      "reviewed_at": null,
      "review_comment": null,
      "publish_at": null,
      "published_at": null
    }
  }
}
```


**Response interpretation:** 201; domain may reject malformed or duplicate slugs.

`data` is the page object; consult the common page/revision field schema above.


## 4. `GET /api/v1/admin/pages/{id}`

**Purpose:** Retrieve the page and published/working revisions.

**Screen:** Dashboard / editor. **Authorization:** Bearer token + `pages.manage`.

**Request contract (field names, types, constraints):** `id`: positive integer path.

**Example request:**

No JSON request body.


**Example response:**

```json
{
  "data": {
    "id": 12,
    "slug": "about-us",
    "locale": "ar",
    "published": null,
    "working": {
      "number": 1,
      "status": "draft",
      "title": "من نحن",
      "body": "<p>نبذة عن المنصة</p>",
      "meta_title": "من نحن",
      "meta_description": "تعرف على المنصة",
      "author_id": 3,
      "submitted_by": null,
      "submitted_at": null,
      "reviewed_by": null,
      "reviewed_at": null,
      "review_comment": null,
      "publish_at": null,
      "published_at": null
    }
  }
}
```


**Response interpretation:** 200; 404 if page missing.

`data` is the page object; consult the common page/revision field schema above.


## 5. `PUT /api/v1/admin/pages/{id}/draft`

**Purpose:** Save changes using optimistic revision number.

**Screen:** Dashboard / editor save. **Authorization:** Bearer token + `pages.manage`.

**Request contract (field names, types, constraints):** `id`: integer path; `base_revision`: required integer min 1; `title`: required string max 200; `body`: present nullable string max 500000; `meta_title`: nullable string max 70; `meta_description`: nullable string max 200; `slug` and `locale`: prohibited.

**Example request:**

```json
{
  "base_revision": 1,
  "title": "من نحن",
  "body": "<p>نبذة عن المنصة</p>",
  "meta_title": "من نحن",
  "meta_description": "تعرف على المنصة"
}
```


**Example response:**

```json
{
  "data": {
    "id": 12,
    "slug": "about-us",
    "locale": "ar",
    "published": null,
    "working": {
      "number": 1,
      "status": "draft",
      "title": "من نحن",
      "body": "<p>نبذة عن المنصة</p>",
      "meta_title": "من نحن",
      "meta_description": "تعرف على المنصة",
      "author_id": 3,
      "submitted_by": null,
      "submitted_at": null,
      "reviewed_by": null,
      "reviewed_at": null,
      "review_comment": null,
      "publish_at": null,
      "published_at": null
    }
  }
}
```


**Response interpretation:** 200; stale base revision or wrong workflow state may be rejected.

`data` is the page object; consult the common page/revision field schema above.


## 6. `POST /api/v1/admin/pages/{id}/draft`

**Purpose:** Start a new working draft from current page.

**Screen:** Dashboard / editor. **Authorization:** Bearer token + `pages.manage`.

**Request contract (field names, types, constraints):** `id`: integer path; no validated body fields.

**Example request:**

No JSON request body.


**Example response:**

```json
{
  "data": {
    "id": 12,
    "slug": "about-us",
    "locale": "ar",
    "published": null,
    "working": {
      "number": 1,
      "status": "draft",
      "title": "من نحن",
      "body": "<p>نبذة عن المنصة</p>",
      "meta_title": "من نحن",
      "meta_description": "تعرف على المنصة",
      "author_id": 3,
      "submitted_by": null,
      "submitted_at": null,
      "reviewed_by": null,
      "reviewed_at": null,
      "review_comment": null,
      "publish_at": null,
      "published_at": null
    }
  }
}
```


**Response interpretation:** 201; workflow may disallow another draft.

`data` is the page object; consult the common page/revision field schema above.


## 7. `DELETE /api/v1/admin/pages/{id}/draft`

**Purpose:** Discard the working draft.

**Screen:** Dashboard / editor. **Authorization:** Bearer token + `pages.manage`.

**Request contract (field names, types, constraints):** `id`: integer path; no validated body fields.

**Example request:**

No JSON request body.


**Example response:**

```json
{
  "data": {
    "id": 12,
    "slug": "about-us",
    "locale": "ar",
    "published": null,
    "working": {
      "number": 1,
      "status": "draft",
      "title": "من نحن",
      "body": "<p>نبذة عن المنصة</p>",
      "meta_title": "من نحن",
      "meta_description": "تعرف على المنصة",
      "author_id": 3,
      "submitted_by": null,
      "submitted_at": null,
      "reviewed_by": null,
      "reviewed_at": null,
      "review_comment": null,
      "publish_at": null,
      "published_at": null
    }
  }
}
```


**Response interpretation:** 200; wrong workflow state may be rejected.

`data` is the page object; consult the common page/revision field schema above.


## 8. `POST /api/v1/admin/pages/{id}/submit`

**Purpose:** Submit the working revision for review.

**Screen:** Dashboard / review workflow. **Authorization:** Bearer token + `pages.manage`.

**Request contract (field names, types, constraints):** `id`: integer path; no validated body fields.

**Example request:**

No JSON request body.


**Example response:**

```json
{
  "data": {
    "id": 12,
    "slug": "about-us",
    "locale": "ar",
    "published": null,
    "working": {
      "number": 1,
      "status": "draft",
      "title": "من نحن",
      "body": "<p>نبذة عن المنصة</p>",
      "meta_title": "من نحن",
      "meta_description": "تعرف على المنصة",
      "author_id": 3,
      "submitted_by": null,
      "submitted_at": null,
      "reviewed_by": null,
      "reviewed_at": null,
      "review_comment": null,
      "publish_at": null,
      "published_at": null
    }
  }
}
```


**Response interpretation:** 200; requires an eligible draft.

`data` is the page object; consult the common page/revision field schema above.


## 9. `GET /api/v1/admin/pages/{id}/revisions`

**Purpose:** List every revision of this page.

**Screen:** Dashboard / history. **Authorization:** Bearer token + `pages.manage`.

**Request contract (field names, types, constraints):** `id`: integer path; no validated query fields.

**Example request:**

No JSON request body.


**Example response:**

```json
{
  "data": [
    {
      "number": 1,
      "status": "draft",
      "title": "من نحن",
      "body": "<p>نبذة عن المنصة</p>",
      "meta_title": "من نحن",
      "meta_description": "تعرف على المنصة",
      "author_id": 3,
      "submitted_by": null,
      "submitted_at": null,
      "reviewed_by": null,
      "reviewed_at": null,
      "review_comment": null,
      "publish_at": null,
      "published_at": null
    }
  ]
}
```


**Response interpretation:** 200; 404 if page missing.

`data` is an array of revision objects with the revision field schema above.


## 10. `GET /api/v1/admin/pages/{id}/diff`

**Purpose:** Compare two revision contents field by field.

**Screen:** Dashboard / revision comparison. **Authorization:** Bearer token + `pages.manage`.

**Request contract (field names, types, constraints):** `id`: integer path; `from`: required integer min 1; `to`: required integer min 1.

**Example request:**

No JSON request body.


**Example response:**

```json
{
  "data": {
    "from": 1,
    "to": 2,
    "changes": {
      "title": {
        "from": "من نحن",
        "to": "عن Outlet"
      },
      "body": {
        "from": "<p>old</p>",
        "to": "<p>new</p>",
        "lines_added": 1,
        "lines_removed": 1
      }
    }
  }
}
```


**Response interpretation:** 200; 404 for missing revision; same revision is rejected.

`changes` is a map keyed by changed content field. Each entry has `from` and `to`; for `body`, `lines_added` and `lines_removed` are integer counts. Unchanged fields are omitted.


## 11. `POST /api/v1/admin/pages/{id}/revisions/{number}/restore`

**Purpose:** Create a new working draft from a previous revision.

**Screen:** Dashboard / history. **Authorization:** Bearer token + `pages.manage`.

**Request contract (field names, types, constraints):** `id` and `number`: numeric path parameters; no validated body fields.

**Example request:**

No JSON request body.


**Example response:**

```json
{
  "data": {
    "id": 12,
    "slug": "about-us",
    "locale": "ar",
    "published": null,
    "working": {
      "number": 1,
      "status": "draft",
      "title": "من نحن",
      "body": "<p>نبذة عن المنصة</p>",
      "meta_title": "من نحن",
      "meta_description": "تعرف على المنصة",
      "author_id": 3,
      "submitted_by": null,
      "submitted_at": null,
      "reviewed_by": null,
      "reviewed_at": null,
      "review_comment": null,
      "publish_at": null,
      "published_at": null
    }
  }
}
```


**Response interpretation:** 201; 404 for missing revision.

`data` is the page object; consult the common page/revision field schema above.


## 12. `DELETE /api/v1/admin/pages/{id}`

**Purpose:** Delete a page only if it has never been live.

**Screen:** Dashboard / delete. **Authorization:** Bearer token + `pages.manage`.

**Request contract (field names, types, constraints):** `id`: numeric path; no validated body fields.

**Example request:**

No JSON request body.


**Example response:**

No response body (HTTP 204).


**Response interpretation:** 204; previously published pages cannot be deleted: unpublish instead.


## 13. `POST /api/v1/admin/pages/{id}/approve`

**Purpose:** Approve for immediate publication or schedule publication.

**Screen:** Dashboard / publication. **Authorization:** Bearer token + `pages.publish`.

**Request contract (field names, types, constraints):** `id`: numeric path; `publish_at`: optional nullable date.

**Example request:**

```json
{
  "publish_at": "2026-12-01T10:00:00+00:00"
}
```


**Example response:**

```json
{
  "data": {
    "id": 12,
    "slug": "about-us",
    "locale": "ar",
    "published": null,
    "working": {
      "number": 1,
      "status": "draft",
      "title": "من نحن",
      "body": "<p>نبذة عن المنصة</p>",
      "meta_title": "من نحن",
      "meta_description": "تعرف على المنصة",
      "author_id": 3,
      "submitted_by": null,
      "submitted_at": null,
      "reviewed_by": null,
      "reviewed_at": null,
      "review_comment": null,
      "publish_at": null,
      "published_at": null
    }
  }
}
```


**Response interpretation:** 200; self-approval depends on server configuration.

`data` is the page object; consult the common page/revision field schema above.


## 14. `POST /api/v1/admin/pages/{id}/send-back`

**Purpose:** Return a submitted page to editor with reviewer comment.

**Screen:** Dashboard / moderation. **Authorization:** Bearer token + `pages.publish`.

**Request contract (field names, types, constraints):** `id`: numeric path; `comment`: required string max 1000.

**Example request:**

```json
{
  "comment": "يرجى تعديل الوصف"
}
```


**Example response:**

```json
{
  "data": {
    "id": 12,
    "slug": "about-us",
    "locale": "ar",
    "published": null,
    "working": {
      "number": 1,
      "status": "draft",
      "title": "من نحن",
      "body": "<p>نبذة عن المنصة</p>",
      "meta_title": "من نحن",
      "meta_description": "تعرف على المنصة",
      "author_id": 3,
      "submitted_by": null,
      "submitted_at": null,
      "reviewed_by": null,
      "reviewed_at": null,
      "review_comment": null,
      "publish_at": null,
      "published_at": null
    }
  }
}
```


**Response interpretation:** 200; sends notification to author when applicable.

`data` is the page object; consult the common page/revision field schema above.


## 15. `POST /api/v1/admin/pages/{id}/unpublish`

**Purpose:** Remove published page from public availability, preserving history.

**Screen:** Dashboard / publication. **Authorization:** Bearer token + `pages.publish`.

**Request contract (field names, types, constraints):** `id`: numeric path; no validated body fields.

**Example request:**

No JSON request body.


**Example response:**

```json
{
  "data": {
    "id": 12,
    "slug": "about-us",
    "locale": "ar",
    "published": null,
    "working": {
      "number": 1,
      "status": "draft",
      "title": "من نحن",
      "body": "<p>نبذة عن المنصة</p>",
      "meta_title": "من نحن",
      "meta_description": "تعرف على المنصة",
      "author_id": 3,
      "submitted_by": null,
      "submitted_at": null,
      "reviewed_by": null,
      "reviewed_at": null,
      "review_comment": null,
      "publish_at": null,
      "published_at": null
    }
  }
}
```


**Response interpretation:** 200; invalid workflow transitions may be rejected.

`data` is the page object; consult the common page/revision field schema above.


## Dashboard / Flutter screen coverage notes

- **Flutter/public:** legal/about/help/content screens that load published pages use `GET /content/{slug}`; exact screen-to-slug mapping requires inspection of client source or `docs/screens` mappings.
- **Dashboard:** page list, page editor, draft creation/discard, submit/review, revision history, diff/restore, publish scheduling, unpublish, delete. Both `/admin/pages` and `/pages` aliases exist.
- **Not verified:** live HTTP tests, frontend code integration, actual screen-by-screen completeness.

## Follow-up checks before marking FULLY VERIFIED

1. Inspect `PublishedPages` and `PageRepository` implementations to document exact public-page and list summary response schemas.
2. Inspect `ApiResponse` and Pages error middleware for exact error JSON/status codes.
3. Compare the real Flutter/Dashboard repositories with these routes.
4. Run authenticated/unauthenticated, validation, revision conflict, and ETag contract tests on staging.


---

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

# Pages — Flutter API

Source: [`modules/Pages/Routes/api.php`](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Pages/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 /content/{slug}`

**Purpose:** Live content page; slug [a-z0-9\-/]+. **Access/middleware:** public; throttle 120/min.

| Contract item | Verified detail |
|---|---|
| Path parameters | `slug` |
| 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 |

