Search Module — Admin

HTTP surface for the platform-admin operational control of the product search index: kick off a (chained) bulk reindex (optionally scoped to one vendor), poll the last reindex's status, and ensure the Typesense collection/alias exist. These are surfaced as action buttons on the Product Search settings group (Admin → Settings → Product Search).

Source: api-modules/search/src/controllers/admin-search.controller.ts.

The search index is normally kept in sync via catalog.* domain events on the queue. This endpoint is the ops escape hatch when the queue has fallen behind, a vendor needs a forced re-sync, or after a schema change in the index.

Conventions

Authentication

All endpoints require a Better-Auth admin session and a role granting the matching permission.

Response envelope

Successful responses are wrapped by ResponseInterceptor:

{
  "data": <payload>,
  "message": "Success",
  "statusCode": 202,
  "metadata": { /* optional, e.g. pagination */ }
}

Error envelope

Endpoints

POST /admin/search/reindex — Kick off a bulk reindex

Required permission: search: reindex. Returns 202 Accepted immediately and processes asynchronously via the search queue. Optionally scope to a single vendor. Re-runnable at any time — re-runs simply re-upsert documents (idempotent).

Body

{
  "vendorId": "01J9...",   // optional — omit to reindex every vendor
  "batchSize": 200          // optional — defaults to DEFAULT_BACKFILL_BATCH_SIZE
}

Response 202

type StartBackfillResponse = {
  runId: string;                   // service-defined identifier for this backfill run
  jobId: string;                   // BullMQ job id of the seed batch
  vendorId: string | null;         // echoes the scope, null when platform-wide
  batchSize: number;
};

The reindex enqueue also stamps a singleton search_reindex_run_state row (startedAt), and the self-chaining backfill stamps finishedAt when it exhausts — the basis for the status endpoint below.

Errors

GET /admin/search/reindex/status — Latest reindex status

Required permission: search: reindex. Returns the last admin-triggered reindex's start/finish timestamps (all null if none has run). The Product Search settings page's "Reindex product search" button polls this until finishedAt advances past its value at trigger time, then stops spinning.

Response 200 — ReindexStatusResponse.

type ReindexStatusResponse = {
  runId: string | null;
  status: "idle" | "running";
  startedAt: string | null;   // ISO 8601
  finishedAt: string | null;  // ISO 8601; null while running / never run
};

POST /admin/search/ensure-collection — Ensure the Typesense collection + alias

Required permission: search: reindex. Idempotent — creates the versioned collection and points the alias at it if missing, otherwise no-ops. Use after a Typesense restore/wipe to recover without redeploying the API.

Response 200 — { ok: true }.

Related modules

• admin-rbac — gates all three endpoints via search: reindex. See admin-rbac.md.
• settings — the search group (titled Product Search) declares registry action buttons ("Reindex product search", "Ensure collection") that call these endpoints; the reindex button polls reindex/status. Typesense connection config stays in deploy-time env, not admin settings.
• catalog — emits catalog.product.* events that drive incremental upserts; this endpoint feeds the queue manually for bulk recovery.
• queue — search backfill jobs run on the BullMQ search queue.