CARIBBEIN
← All notes

Engineering note · reference

The public read API, as observed

When you open the marketplace, your browser calls a handful of read-only endpoints. They are public by construction — so here they are, documented the only honest way an unversioned API can be.

August 2026 · shapes observed —

No contract yet. These endpoints are unversioned and may change without notice until a versioned contract ships. This page is observation, not promise: it describes what the marketplace itself reads today, on the date shown. If you build against it, build the way we do — tolerant of extra fields, ready for shape drift.

The provider directory

The whole consumer directory, read-only, no auth. Results are ranked, and one response is capped at roughly a thousand rows — to enumerate everything, do what the marketplace does: fetch the top page plus one page per category, and deduplicate by id.

GET https://app.caribbein.fr/api/providers?limit=1000
GET https://app.caribbein.fr/api/providers?limit=1000&category=resto

# response shape
{ "providers": [ { "id": "…", "name": "…", "category": "resto",
    "subcategory": "…", "island": "…", "side": "…",
    "description_en": "…", "description_fr": "…",
    "logo_url": "…", "rating_avg": 4.6, "review_count": 12,
    "lat": 18.0, "lng": -63.0, "price_range": "…",
    "website": "…", "whatsapp": "…", "phone": "…",
    "verified": true, "langs": ["en","fr"],
    "open_days": "…", "open_time": "…", "close_time": "…" } ] }

Fields worth knowing: descriptions come in both languages in the row itself (see why); logo_url is first-party imagery under our rights model, absent when honesty demands it; coordinates are present where a geolocation pass has confirmed them. Expect more fields than shown — tolerate them.

Events

Public events across the islands — festivals, weekly nights, tournaments. Bilingual titles and descriptions in the row, dates and times with a timezone, tournament metadata where the event is one.

GET https://app.caribbein.fr/api/events

# response shape
{ "events": [ { "id": "…",
    "title_en": "…", "title_fr": "…",
    "description_en": "…", "description_fr": "…",
    "event_type": "…", "island": "…", "location": "…",
    "event_date": "2026-09-…", "event_time": "…", "timezone": "…",
    "is_free": true, "price_pp": null, "currency": "…",
    "image_url": "…", "organizer_name": "…",
    "is_tournament": false, "recurrence": null } ] }

Ground rules

  • Read-only. Everything above is GET. Write endpoints exist for the product's own flows and are not documented here on purpose.
  • Be polite. The full enumeration is about twenty requests; cache the result. If you need a daily feed of the whole catalogue, ask us instead of polling: welcome@caribbein.fr.
  • The data is the venues'. Listings describe real businesses under our rights model. Republish facts, not our imagery.

Check it now

Every claim on this page is one curl away, and probe.mjs is a working client for the directory — it is exactly the enumerate-and-dedup loop described above, in forty lines you can read first.