# NEXX PLATFORM — Pagination / Search contract · PLANNED / NON-LIVE

> **Status: PLANNED / NON-LIVE.** This is the proposed contract *shape* for
> Zone 13 (pagination/search). It is **not yet implemented**. The live
> contract remains **v1.5.2** (see `frontend-handoff.json` /
> `openapi-internal-v1.json` on this landing). **Do not** run
> `api:generate` / `api:check` against this note — when the backend
> implements and smoke-confirms, it ships as live **v1.6.0** via the normal
> artifact flow.

Frozen & accepted: **2026-06-11**, Telegram "NEXX Platform NAD", msgs #248–#252.

## Why this exists

Stage 3 search (D3.1–D3.2) must not be built on the full-list pattern. This
freezes the pagination/search contract *shape* so the frontend can design
D3.1–D3.2 against a final model **before** backend implementation, and not
rebuild later.

## Envelope (additive, backward-compatible)

- The existing domain key of each list response is **preserved**:
  `items` / `suppliers` / `orders` / `relationships`.
- Added **alongside** it: `total`, `limit`, `offset`.
- `limit`: default **50**, max **200**. `offset`: default **0**.
- `total` = count **after filters, before slice**.
- Deterministic ordering (per-endpoint below).
- Existing fields are unchanged → current v1.5.2 clients keep working.

Example response shape:

```json
{
  "items": [ /* ...page... */ ],
  "total": 134,
  "limit": 50,
  "offset": 0
}
```

## Endpoints (first bump)

### `GET /api/internal/v1/catalog/items/`
- Filters: `q`, `supplierId`, `categoryId`, `mine` (already live) + `limit` / `offset` / `total`.
- Plus `area=<key>` (BKG-009, same v1.6.0 package) — see
  `procurement-area-planned-v1.6.0.md`.
- **Server-side search** (not frontend full-list). `pg_trgm`/FTS is a
  backend-internal decision and does not change the contract shape.
- Price-visibility / orderability are computed **per page, after slice**.
- Ordering: deterministic by `id`.

### `GET /api/internal/v1/catalog/suppliers/`
- `q` by **supplier name** + `limit` / `offset` / `total`.
- Plus `area=<key>` (BKG-009, same v1.6.0 package) — see
  `procurement-area-planned-v1.6.0.md`.
- Ordering: deterministic by `id`.

### `GET /api/internal/v1/orders/`
- `status` filter (order lifecycle: `created` / `confirmed` / `shipped` / `delivered` / …) + `limit` / `offset` / `total`.
- Default ordering: **`-id`** (newest first).

### `GET /api/internal/v1/relationships/`
- `limit` / `offset` / `total`.
- Ordering: deterministic by `id`.

## Boundary (important)

- This is a **PLANNED / NON-LIVE** contract shape for D3.1–D3.2 planning only.
- Live OpenAPI / handoff stays **v1.5.2** — **not** modified by this note.
- `api:generate` / `api:check` run **only after** live v1.6.0 artifacts ship.
- Backend implementation begins **after Stage 2 sign-off** (TDD, additive
  only); **v1.6.0** is published **only after backend smoke**.
- The shape is **open to frontend edits** until implementation begins.

---

Source of truth: Telegram "NEXX Platform NAD" #248–#252. Questions → same chat
or GitHub issues on `grabbly/nexx-platform-backend`.