Start a session data backfill (super_admin)
Start an in-memory background backfill for one WhatsApp session, re-pulling the directly fetchable WhatsApp data for that number. The job pulls only the data WhatsApp exposes through a direct fetch: **cached contacts** and **joined group metadata/members**. Ordinary chat history is **not** part of a backfill — message history arrives asynchronously through WhatsApp `HistorySync` events, and there is no generic "fetch all messages" API. ### Asynchronous behavior - Returns **202 Accepted** immediately with the created/running `BackfillJob`; the work continues in the background. - Poll `GET /admin/sessions/{session}/backfill` to observe progress and completion. ### Idempotency / concurrency - At most **one** backfill may run per session at a time. If a backfill is already in progress for this session, the request is rejected with **409** rather than starting a second one — it is **not** a no-op merge into the existing job. ### Preconditions - Requires the platform **super_admin** role (login JWT only; api-keys and org roles are rejected with 403). - The session must exist. ### Errors - `forbidden` (403) — caller is not a platform super_admin. - `not_found` (404) — no session with the given id exists. - `conflict` (409) — a backfill is already running for this session; wait for it to finish (poll the status endpoint) before retrying. - `not_implemented` (501) — backfill is unavailable in this build/configuration for the requested session.
Send Authorization: Bearer <token>. The router accepts two kinds of token and tries each in turn: a frontend-minted login JWT (verified against the frontend JWKS; the person's org + role are read from it), or an api-key for a script/service (carrying a fixed set of gateway permissions). The bearerFormat: JWT label describes the person-login case.
In: header
Path Parameters
The WhatsApp session id to target. A session is one attached WhatsApp number; the id is the opaque session identifier returned by the session list/create endpoints (it is not the phone number). As a super_admin endpoint this may name a session owned by any organization, not only the caller's.
Response Body
application/json
application/json
curl -X POST "https://example.com/api/v1/admin/sessions/01HZX9Q2K7:backfill"{ "contacts": 128, "error": "session not connected", "finishedAt": 1719662460000, "groupMembers": 342, "groups": 14, "id": "01J9...", "organizationId": "org_01J9ABC...", "sessionId": "01J9ZX8K2QHV0M3T6R7P4N5W8C", "startedAt": 1719662400000, "status": "succeeded"}{ "error": { "code": "not_found", "details": { "property1": null, "property2": null }, "message": "session not found" }}Get the current or latest session backfill job (super_admin) GET
Return the **current or most recent** backfill job for one WhatsApp session. Use this to poll a backfill started with `POST /admin/sessions/{session}:backfill`: it reports the job's status and progress. If a backfill is in progress, the running job is returned; otherwise the last completed/failed job for the session is returned. ### Semantics - Read-only. Backfill state is held **in memory**, so a gateway restart clears it: after a restart this returns 404 until a new backfill is started. ### Preconditions - Requires the platform **super_admin** role (login JWT only; api-keys and org roles are rejected with 403). ### Errors - `forbidden` (403) — caller is not a platform super_admin. - `not_found` (404) — the session does not exist, or no backfill job is on record for it (e.g. none has been started since the last gateway restart).
List sessions GET
Lists the sessions (attached WhatsApp numbers) belonging to the caller's organization. Requires the `manage` capability. Each item shows the session's current status, the attached number once paired, and which gateway currently holds it. The response is org-scoped — sessions in other organizations are never returned. **Pagination.** This list is returned in a single page (no cursor is consumed); the response carries a `nextCursor` field for forward compatibility, which is null when there are no further pages. **Errors.** `unauthorized` (401) — missing or invalid credentials. `forbidden` (403) — the caller lacks the `manage` capability.