Search Module — Admin

HTTP surface for the platform-admin operational control of the product search index. Currently a single endpoint: kick off a (chained) bulk reindex of the search index, optionally scoped to one vendor.

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

Progress is tracked via search queue logs / dashboards — there is no synchronous result.

Errors

Related modules

• admin-rbac — gates the endpoint via search: reindex. See admin-rbac.md.
• 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.