​
Plain-language flow

  1. Identity — Every authenticated request is scoped to the Clerk user carried in your bearer token. Sessions, groups, messages, and alerts belong to that tenant.
  2. WhatsApp link — The user connects WhatsApp through a session (usually a “receiving” session). Until the session is working and groups are chosen, little product data appears.
  3. Group selection — Groups discovered from WhatsApp start off for ingest into feeds. You enable the groups you want so their messages participate.
  4. Downstream data — List endpoints return stored projections keyed off canonical IDs (canonical_message_id, listing IDs, etc.). Data appears after ingest and processing; the API answers what is stored now, not a live WhatsApp socket.
  5. AI classification — Optional pipelines attach structured watch data to messages. Market-style endpoints aggregate classified listings where that projection exists — availability evolves with the product; always verify behaviour against the live API reference.

​
Practical expectations

  • Pagination: Message-style collections favour cursor/keyset style paging — prefer returned cursors over naive offsets where documented.
  • Consistency: Immediately after a write, a subsequent read may lag slightly; retries with backoff are reasonable if you enforce ordering on your side.
  • Errors: JSON error bodies with HTTP status codes (401 for missing/invalid auth, 403 for tenancy or capability denials, 404 for unknown IDs, validation failures as 4xx). Exact schemas are in the reference.
Nothing here replaces the OpenAPI definitions — use them when integrating fields and enums.