JEK · Developer

Native Supabase Auth. Responses use {code,message,data}. Success code=200; failures use HTTP 400/401/403/409/429/503. No legacy/Wonder consumer authentication.

Native Supabase Auth. Responses use {code,message,data}. Success code=200; failures use HTTP 400/401/403/409/429/503. No legacy/Wonder consumer authentication.

Native Supabase Auth. Responses use {code,message,data}. Success code=200; failures use HTTP 400/401/403/409/429/503. No legacy/Wonder consumer authentication.

Native Supabase Auth. Responses use {code,message,data}. Success code=200; failures use HTTP 400/401/403/409/429/503. No legacy/Wonder consumer authentication.

Native Supabase Auth. Responses use {code,message,data}. Success code=200; failures use HTTP 400/401/403/409/429/503. No legacy/Wonder consumer authentication.

Native Supabase Auth. Responses use {code,message,data}. Success code=200; failures use HTTP 400/401/403/409/429/503. No legacy/Wonder consumer authentication.

Native Supabase Auth. Responses use {code,message,data}. Success code=200; failures use HTTP 400/401/403/409/429/503. No legacy/Wonder consumer authentication.

Native Supabase Auth. Responses use {code,message,data}. Success code=200; failures use HTTP 400/401/403/409/429/503. No legacy/Wonder consumer authentication.

Native Supabase Auth. Responses use {code,message,data}. Success code=200; failures use HTTP 400/401/403/409/429/503. No legacy/Wonder consumer authentication.

Native Supabase Auth. Responses use {code,message,data}. Success code=200; failures use HTTP 400/401/403/409/429/503. No legacy/Wonder consumer authentication.

Native Supabase Auth. Responses use {code,message,data}. Success code=200; failures use HTTP 400/401/403/409/429/503. No legacy/Wonder consumer authentication.

Native Supabase Auth. Responses use {code,message,data}. Success code=200; failures use HTTP 400/401/403/409/429/503. No legacy/Wonder consumer authentication.

Native Supabase Auth. Responses use {code,message,data}. Success code=200; failures use HTTP 400/401/403/409/429/503. No legacy/Wonder consumer authentication.

Native Supabase Auth. Responses use {code,message,data}. Success code=200; failures use HTTP 400/401/403/409/429/503. No legacy/Wonder consumer authentication.

Native Supabase Auth. Responses use {code,message,data}. Success code=200; failures use HTTP 400/401/403/409/429/503. No legacy/Wonder consumer authentication.

Native Supabase Auth. Responses use {code,message,data}. Success code=200; failures use HTTP 400/401/403/409/429/503. No legacy/Wonder consumer authentication.

Native Supabase Auth. Responses use {code,message,data}. Success code=200; failures use HTTP 400/401/403/409/429/503. No legacy/Wonder consumer authentication.

Native Supabase Auth. Responses use {code,message,data}. Success code=200; failures use HTTP 400/401/403/409/429/503. No legacy/Wonder consumer authentication.

Native Supabase Auth. Responses use {code,message,data}. Success code=200; failures use HTTP 400/401/403/409/429/503. No legacy/Wonder consumer authentication.

Native Supabase Auth. Responses use {code,message,data}. Success code=200; failures use HTTP 400/401/403/409/429/503. No legacy/Wonder consumer authentication.

Public runtime config for web and native clients: API base, map keys scope, feature flags and channel branding.

Returns a session id and QR payload to display. Poll /api/wonder/qr-poll until it resolves.

AI helper used by the voice assistant to turn speech into structured pickup / dropoff / options.

Transparent pass-through used while legacy Go/Node routes are being migrated. Signs Wonder gateway requests from the caller's session headers.

Server-owned STG Ride location primitive. With an empty `input` it recommends places before the rider types — saved Home/Work/custom places, repeated and recent trips, and real nearby points of interest, ranked by distance, recency, frequency and weekday/time-of-day (docs/25 §3). With a non-empty `input` it merges provider autocomplete with the rider's own places, keeping exact saved matches on top. Every row carries a stable `reason` code (current_location, nearby_pickup, nearby_poi, saved_home, saved_work, saved_place, recent_pickup, recent_destination, frequent_pickup, frequent_destination, repeated_route, commute_pattern, autocomplete), a `source`, `distance_m` and a QA `score`; `meta.ranking_version` names the ranking. The frontend still shows the live GPS row itself, removes what is already selected and trims to 10. The rider comes from the bearer; no user id is read from the body.

Server-owned STG Ride location primitive. The mobile client never calls the map or Wonder provider directly.

Server-owned STG Ride location primitive. The mobile client never calls the map or Wonder provider directly.

Server-owned STG Ride location primitive. The mobile client never calls the map or Wonder provider directly.

Server-owned STG Ride location primitive. The mobile client never calls the map or Wonder provider directly.

Driving route used to render the booking map and feed distance into fare quotes. The path keeps its trailing underscore (the bare /route segment is reserved by the router).

Resolves Standard Ride places server-side, returns real Wonder quotes and persists the owned, expiring batch before responding.

Authenticated passenger-trip operation used by the STG Standard Ride flow.

Authenticated passenger-trip operation used by the STG Standard Ride flow.

Authenticated passenger-trip operation used by the STG Standard Ride flow.

Authenticated passenger-trip operation used by the STG Standard Ride flow.

Authenticated passenger-trip operation used by the STG Standard Ride flow.

Authenticated passenger-trip operation used by the STG Standard Ride flow.

Authenticated passenger-trip operation used by the STG Standard Ride flow.

Authenticated passenger-trip operation used by the STG Standard Ride flow.

Authenticated passenger-trip operation used by the STG Standard Ride flow.

Authenticated passenger-trip operation used by the STG Standard Ride flow.

Accepts batch_id and selected_quote_ids only. Locations and prices are re-read from the caller's unexpired server-owned quote batch.

Records caller-supplied payment confirmation and then creates the Wonder taxi order. It does not charge a payment method.

For a Wonder order id, focus=false previews cancellation, focus=true confirms it, and submit_reason_only=true submits post-cancel feedback. Native UUID orders use the migration dispatcher.

Preserves the existing Standard Ride client contracts while moving behavior-compatible Wonder order creation, lifecycle, history, route, edit, rating, and Live Activity operations onto the stable API origin. Payment-coupled and map-search operations are intentionally excluded.

Creates a ride request with optional wish text/audio, analysis metadata and tip. Send vehicle_class_ids to accept several classes at once and be matched by whichever driver turns up first: the selection is priced HERE and the passenger is charged the DEAREST of it, so the fare is covered whichever class arrives. The request's own `fare` is not consulted for a selection — a caller who named its own total would also get to decide which class counted as dearest. Send duration_min alongside it, or the reprice drops the per-minute component and lands under the quote you showed. Refuses a pickup whose service area is fulfilled by PARTNER capacity with 422 `PARTNER_FULFILMENT_REQUIRED`, carrying `fulfilment` and `fulfilment_area`: that market is served by a third party through Wonder, and this lane has no payment gateway to buy it with. Call /api/v1/ride/preflight first to learn which fulfilment applies.

Marks the caller's own order cancelled and records the reason in the wish metadata. Returns 409 if the order is already completed/cancelled, if a driver has already accepted it (code WISH_ALREADY_CLAIMED), or if the status changed concurrently (code WISH_CHANGED). No refund transaction is written.

Rider-facing read of the assigned driver's most recent GPS ping. Poll while the order is accepted / in progress.

The single read the trip screen polls. Scoped by id AND user_id — a ride belonging to someone else answers 404, never 403, so ids cannot be probed. The payload is additive: each feature (driver, cancellation, receipt, events, coupons…) contributes one sibling key, while `fare` stays a bare number for compatibility with older app builds.

Answers 'what would happen if I cancelled right now' — whether it is allowed and what it would cost — using the same stored policy and evaluator as POST /cancel, so the preview cannot disagree with the charge. Writes nothing.

How the passenger reaches the driver without either side learning the other's number: a pooled virtual number held for this ride, plus an in-app chat conversation. Offered only while the ride is live; an empty number pool returns 200 with available:false rather than ever exposing the driver's real mobile.

Re-rides the pricing server-side: the request names where to, never a fare. Only the difference between the old and new route's class price moves — boosts, surcharges and tips on top stay on top — and after a driver has claimed the ride the fare can only go up.

Name, plate and rating of the driver working this ride, while they are working it. Gated exactly like /driver-location: caller's own ride only (404 otherwise), and the response goes dark when the trip ends. The permanent record stays on GET /api/v1/me/rides/{id}'s driver block.

Cursor-keyed replay of what has changed since the client last asked. The realtime nudge is a Supabase Realtime broadcast on `realtime.topic` (`order:ride:{id}`), published on every lifecycle transition; subscribe to it and call this with the cursor when it fires, or poll at `poll_after_ms` without it. Not SSE/websockets: the deployment is a Cloudflare Worker with no long-lived connections. Events carry `at` (when the row says it happened) beside `observed_at`. Also folds in `driver_location`, `remaining_route` (driver → pickup/drop-off, provider route or a labelled straight-line estimate), `timestamps`, and `actions` — including `can_cancel` from the same cancellation policy the detail and cancel endpoints use, and `can_end_trip`.

Only while `in_trip` — the same predicate the detail publishes as `actions.can_end_trip`. Idempotent: a repeat answers the same success with `already: true`. Writes `status=completed`, `completed_at` and `wish.earlyEnd`; the driver's trip count is bumped exactly as their own completion would (never on a test job) and both parties are notified. No money moves (Module A). 409 `not_in_trip` / `already_finished` / `RIDE_CHANGED`.

Mints a 256-bit token (returned once, stored hashed) and a public URL (`GET /api/public/v1/trip-shares/{token}`) that serves a minimised live view: phase, short pickup/drop-off labels, driver first name + plate + vehicle, the car's last position while the trip is active, lifecycle times. Never the rider's name/phone, the driver's phone, the fare or addresses beyond the labels. Default TTL 4h (`ttl_ms`, 10 min – 24 h), at most 5 live links per order, revocable. 409 `order_finished` / `too_many_links`.

Every live link on the ride, or one by `?id=`.

Unauthenticated: the token is the credential. Serves a small HTML page to browsers (auto-refreshes while the trip is active) and the JSON `SharedTripView` to `Accept: application/json` / `?format=json`. Invalid, expired and revoked tokens all answer the same 404. Rate-limited per token.

Idempotent on `Idempotency-Key` (header or `idempotency_key` body): the same key returns the same event and sends nothing again; without one, presses within a minute collapse. Records the event, mints a share link, and sends one SMS to each VERIFIED emergency contact (optionally narrowed by `contact_ids`) through the configured SMS provider. Every attempt is a `notifications[]` row with a delivery status: `sent`/`failed` with the provider reference, `simulated` on staging without a provider, `skipped:notification_provider_unavailable` elsewhere without one, `skipped:contact_unverified`. 201 on create, 200 on a repeat.

Trip-scoped: the ActivityKit push token is bound to this ride only (unique per ride + token; a repeat re-registers). Updates are pushed on every lifecycle transition and an `end` on completion/cancellation/expiry, through APNs when `APNS_*` is configured — `meta.configured: false` means the registration is kept and nothing is faked. 409 `order_finished`.

All of them, or one by `?push_token=`. Sends ActivityKit `end` when APNs is configured.

A position in the trip's audit log (`jek_passenger_trip_events`): `?cursor=` is the last event the client saw, the answer is every passenger-visible event after it in log order, and the new cursor is the last one returned. `?refresh=1` first polls Wonder DA (the detail's refresh leg) so one call both advances the trip and reads what moved. The realtime nudge is the broadcast topic `order:trip:{id}`. Payloads are never spread — each event carries `{id,type,source,from,to,at,detail}`.

Only while `in_progress` — the predicate the detail publishes as `capabilities.allow_early_end_trip`. Idempotent (`already: true` on a repeat). Completes the trip on JEK's side (`status`, `completed_at`, `early_end`) and records `trip.ended_early`; Wonder DA has no passenger-side end, so `upstream.ended` is false and `supply_status` keeps following the supplier's order without ever reopening the trip. 409 `trip_not_in_progress` / `trip_changed`.

The Wonder driver must first resolve to a Driver Pro profile (matched by Wonder id or phone; the outcome is remembered on the trip and is what `capabilities.allow_chat` / `allow_chat_reason` report). Opens the same thread model the Wish lane uses, so `/api/v1/me/messaging/*` and the driver's `/api/v1/da/wishes/{id}/messages` serve it. 409 `driver_not_on_jek` / `TRIP_NO_DRIVER` / `TRIP_NOT_LIVE`. `GET` reads the state without opening.

The same server-owned catalog the Wish lane uses (`system_configs['ride.cancellation']`), filtered to the trip's stage, with `catalog_version`. `POST …/cancel` accepts `reason_code` (or the legacy numeric `reason_id`); only catalog codes are stored as codes, anything else becomes a note. `GET /api/v1/passenger/catalogs` returns the whole catalog with the same version.

Same contract as `POST /api/v1/me/rides/{id}/share`; `GET` lists, `DELETE` revokes (`?id=` for one).

Same contract as `POST /api/v1/me/rides/{id}/sos`; `GET` lists events with delivery audit, `DELETE ?event_id=` resolves.

Same contract as `POST /api/v1/me/rides/{id}/live-activity`, plus the token is bound upstream (Wonder DA `bind_apn_token`, best-effort, `upstream_bound`) once the supplier order exists so Wonder's own updates reach the same activity. `GET` lists, `DELETE ?push_token=` ends.

The mirror of /api/v1/da/location: the passenger shares their fix with the assigned driver, only while a driver is coming. Treated as a home address — caller's own ride only, live window enforced, DELETE stops sharing immediately.

An itemised account of what the ride cost and what was actually charged, assembled from the transaction rows and the sealed pricing pin stored at booking. It reports; it does not re-price — editing the rate card later cannot rewrite an issued receipt.

Adds money for the driver once the trip is finished — the mirror image of /boost, which is only legal while the ride is still waiting. Same ownership check and payment ledger as boost.

Creates ONE Wonder payment order for the ride and returns its `number` plus the `client_secret` the in-app Wonder Payment SDK renders its payment sheet against — no card data, token or 3DS step touches this server. The fare is one `Charge` line and each voucher is a NEGATIVE `Charge` line beside it, so the passenger owes the discounted total and the order itself records why; `jek_rides.fare` is untouched because it is the driver's payout basis. Call it when the passenger is about to pay, not at booking: the client_secret expires in about two hours and Wonder offers no way to mint a second one for an existing order, so a repeat call answers with the order but `client_secret_available: false`. Idempotent by construction — the order is keyed at Wonder on the ride id, and Wonder refuses a duplicate reference, so one ride can never have two orders. 409 FREE_RIDE when a voucher covers the whole fare. Card payment is open on EVERY declared environment — dev and staging hit gateway-stg where no real money moves, while alpha and production share one payment appId and both bill Jek Limited's real merchant record, so alpha is not a rehearsal. Only two things close it: `JEK_RIDE_PAYMENT_ORDERS_ENABLED=0` as an emergency stop, and an environment that has not declared itself, which cannot name the gateway it would bill.

Reads the merchant's own order back from Wonder and, when it reports the money arrived, records the fare leg in jek_payment_charges. THE ORDER IS THE AUTHORITY: a client saying the payment sheet succeeded is a claim, `correspondence_state` on Jek Limited's order is a fact. Safe to poll — the charge row is keyed on the ride and leg, so one payment is recorded once however many times this is called. Answers `{data: null}` when no order has been opened.

Server-side 'HK$230, less HK$40 = HK$190' for the booking screen: prices the selection from the rate card (the same priceSelection the quote and booking routes use) and applies the coupon rule. The request never carries a fare, so the discount cannot be chosen by the client.

Multiplexed state-machine action endpoint. Passenger actions and driver actions (arrived, start, end) share the route; the caller's role decides which transitions are allowed.

The driver's whole wish surface in one read: `data` is the open pool (no driver yet), `mine` is every wish the caller holds in any state, and `can_accept` says whether a claim from this driver would be allowed at all. Rows are sanitised for the driver — the passenger's `fare` and the `wish.pricing` pin are stripped — and only `mine` carries passenger contact details.

Claims a wish, first driver wins via a conditional update on `driver_id`. Returns `{ data, served_vehicle_class, refunded? }` where `data` is the full claimed wish row with `status: "accepted"` — clients render from it rather than re-reading the feed. Refuses with 403 when the driver is not eligible to take work or their active vehicle serves no class the order accepts, and 409 "Wish already taken" when another driver got there first. Unlike the list endpoint, the row returned here is RAW, so a driver-facing relay must strip `fare` and `wish.pricing` itself.

Returns the signed-in driver, their vehicles, documents and an onboarding checklist. The profile is provisioned automatically on first call.

Only approved drivers with an active vehicle may go online.

Send is_active=true to make this the vehicle used for new orders. Sending vehicle_type_codes REPLACES the approved class set rather than adding to it, so a class claimed in error can be taken back.

Returns a short-lived URL; PUT the file to it, then register it with POST /api/v1/da/documents.

Live offers for the signed-in driver. Empty while offline or when onboarding is incomplete.

First accept wins; a losing caller receives 409 Order already taken.

accepted → arrived → in_trip → completed (cancel allowed before in_trip). Completing an order writes the earnings row and mirrors the state to the rider platform.

Updates the driver's live position and, when on a trip, the trail shown to the rider.

The driver's half of `/api/v1/me/push-tokens`. Without a row here `fanOutPush` has nothing to deliver to and a passenger's chat message never rings. Expo tokens only — Driver Pro's native builds are the only client, and its web build has no service worker or VAPID keys. Idempotent on the token itself (a handset that changes hands re-points to whoever registered last). The row is written under `da_drivers.user_id`, which is what conversation membership keys on; a driver with no messaging identity gets 409 `driver_has_no_identity`. `DELETE ?expo_token=` retires the caller's own row on sign-out.

Demand-platform intake (JEK, Uber, Grab, ComfortDelGro…). Creates a supplier order and broadcasts it to eligible online drivers. Authenticated with the X-Internal-Token dispatch token. Send your own order id as external_ref: a repeat POST with the same external_ref and demand_platform_code returns the existing order (200, idempotent:true) instead of dispatching a second driver, so a timed-out request is safe to retry.

Reconciliation, not polling. Status callbacks are best-effort and unordered, so a demand platform that missed one needs to ask what happened. `{id}` accepts our order id OR your own external_ref, because a partner often keeps only its own reference. Authenticated with the X-Internal-Token dispatch token.

Stands a driver down, including after they have accepted — without this a driver keeps going to a pickup nobody is waiting at. Allowed through in_trip; refuses a completed trip (that is a refund conversation); idempotent once terminal. Outstanding offers are expired in the same breath.

Widen an unmatched order instead of cancelling and re-booking, which loses its place in the queue, or placing a second order, which dispatches two drivers to one passenger. Widening only — classes are never removed, since a driver may already be heading over on one of them. The first class of the set stays the primary, so vehicle_type_code never changes under a partner who has already told their passenger what is coming. 409 once a driver has taken it, enforced again in the write so a driver accepting mid-request cannot have the order changed underneath them. Re-sending classes the order already accepts answers 200 with unchanged:true, so a timed-out call is safe to retry. `{id}` accepts our order id OR your own external_ref.

Driver-side state transition for a wish the caller holds: accepted → arrived → in_trip → completed, with cancelled available until the trip starts. The body field is `state`, NOT `status`. Returns `{ data }` — the full updated wish row, which is what the driver app renders from rather than re-reading the feed. Refuses a disallowed move with 409 `{ error, allowed: [...] }` naming the transitions it would have accepted, 409 "Wish changed concurrently" if the status moved under the caller, and 404 for a wish the caller does not hold.

Submits an out-of-pocket expense (amount, note, uploaded receipt path) for the wish the driver is running.

Returns a short-lived signed URL into the driver-documents bucket for the receipt image.

The driver's side of the thread `POST /api/v1/me/rides/{id}/contact {channel:'chat'}` opens. Only for an order this driver holds (`driver_id`); `can_post` reflects the same liveness gate the passenger side applies. `viewer_id` is the caller's own messaging id — compare it with a message's `sender_id` to tell their messages from the passenger's; a client has no other way to learn what JEK calls it.

Sends into the ride's thread, creating it if the passenger has not opened it yet. Only while the driver holds a live order — 409 `RIDE_NOT_LIVE` otherwise. The passenger is pushed the message like any other.

Makes / models / classes a driver can bind to their vehicle; the same catalogue M1OS servicing uses.

Token-authenticated integration endpoint. All channels funnel into the same supplier order queue.

Called by the scheduler to advance offers, expire stale ones and fall back to external supply.

Token-authenticated (MIGRATION_ADMIN_TOKEN) migration runner used by the admin migration console.

Composes and validates the documented body before a token is spent — `client_id` is filled in from the env's saved beams config unless the caller names one — then returns the upstream's status and body verbatim alongside the `x-request-id` the send carried — the handle Wonder traces a missing message by. A 4xx here means nothing left api.jek.app; beams' own refusal arrives as 200 with `ok: false`.

Trip-kind guard is DB-enforced; `commissionable` marks the components commission is computed on (the Wonder settlement adapter reads it); renaming a rule or flipping a flag changes future pricing only, never issued receipts.

Read-only verification harness: send an encoded polyline (+ optional overrides) and get back what the engine would charge and why, without writing a rule. Used to validate toll geofence coordinates before they bill a passenger.

Bulk insert of workers, locations and package pricing. Insert-only with upsert-ignore: re-running the same file is a no-op and nothing existing is ever updated in bulk. Reports per-table received/inserted/skipped/errors.

Two rails from one record: `link` issues a Wonder H5 payment page; `cash` records a driver's claim to have collected, pending admin approval (`cash_approve` / `cash_reject`). `link` and `cash` are also open to the m1os_operation role (counter staff); approval actions stay admin-only.

Per-environment Wonder config. wonder_env (staging|production) decides which RSA key signs and which Wonder host bills; leaving it on production while testing sends real bills.

Returns the public key and fingerprint only — the private key never leaves the server.

Search & filter public merchant directory.

The rate card, already in the order a passenger should read it: Standard, Express, Meter, 85% Meter, Premium, 6-seater, Wheelchair, Extra Luggage, then anything else by name. Render the array as it arrives. A client that must re-sort may only sort by `sort_order` — the operator's own ordering from /admin/ride/vehicle-types, which this response already honours — never by name or price, which is a different running order for the app.

Prices one vehicle type, or a whole selection. Send vehicle_class_ids to price several at once: the response adds `authorize`, the dearest of them, which is what the passenger pre-authorises so that whichever driver accepts, the fare is already covered. The selection is priced in one call on purpose — quoting each class separately would let the client decide which counted as dearest. A quote takes up to 24 ids — the whole rate card, so a price list is one call, no batching — while a booking accepts at most 6; the response echoes that as vehicle_class_limit. A class can have a MINIMUM FARE — 85% Meter Taxi is not offered below HKD 90, because a discounted short trip is a job no driver takes. On a trip that prices under it the class is dropped from `quotes` and listed in `withheld` with the floor it missed, so a price list drawn from `quotes` loses the row by itself. 400 BELOW_CLASS_MINIMUM when nothing clears its floor, or when vehicle_type_id named such a class; POST /api/v1/me/rides refuses the same class with the same code rather than dropping it, so a stale screen cannot book one.

Widens what an unmatched ride will accept. Only the DIFFERENCE is charged — the passenger already authorised the previous dearest class, so a cheaper addition costs nothing and a dearer one costs the gap. Widening only: classes are never removed, because that could strand a driver already on the way. 409 once a driver has taken it.

Raises the fare on an order no driver has taken. Wishes and ordinary rides both. Refused once a driver is attached.

The reason chips a finished Lane 1 trip offers, with a `catalog_version` derived from the catalog's content so a client can cache against it. Each entry carries `code`, `label_key` (a translation key the client resolves — the server never sends an English label, which would be wrong in three of the four shipped locales), an operator `label` override or null, and `sentiment`. Managed in `system_configs['ride.rating']` beside the rating windows; POST /api/v1/me/rides/{id}/rating validates against this same list, so an added reason is stored rather than dropped.

The authoritative Lane 1 answer Standard Ride and JEK Wish both run before opening a quote/request screen. 200 = serviceable, with the summed route (`distance_m`, `duration_min`, stitched `points`). 422 `OUT_OF_SERVICE_AREA` = definitively unsupported — a waypoint outside every configured service area, or a leg the router says has no road; refuse, do not retry. 503 `ROUTING_UNAVAILABLE` = temporary, offer Retry (never shown as "unavailable here"). 401 `AUTH_REQUIRED`. Service areas come from `system_configs['ride.service_area']`, shared with /api/v1/passenger/serviceability. `dropoff` is optional: with a pickup alone this answers the area question only, which is what a landing screen needs. No supply probe — that would sign with Wonder DA, which Lane 1 exists to avoid. Also returns `fulfilment` (`jek` = our own fleet, `partner` = third-party capacity through Wonder for a market where JEK has no fleet) and `fulfilment_area`. THE CLIENT READS THIS, IT NEVER DECIDES IT: a JEK passenger books through the same surface wherever they are standing, and the server picks the supplier from each area's `fulfilment`, maintained at /admin/ride/service-areas. The PICKUP decides — a Hong Kong pickup bound for Shenzhen is still `jek`. On `partner` our own service areas stop constraining the other waypoints (they describe where OUR fleet drives), though an undrivable leg still refuses. `fulfilment` is null on a 422 whose pickup nobody serves.

Is there a car for this pickup, which classes can serve it, and how long until one arrives — the third pre-booking question, beside /ride/preflight (may we drive here) and /ride/quote (what does it cost). Counts `da_drivers` that are online, approved, carrying a fix newer than 150s, inside the radius and not already on a job; a driver whose vehicle declares no dispatch class is UNRESTRICTED and counts for every class, exactly as the accept path reads it. Deliberately NOT /passenger/serviceability's probe, which signs with Wonder DA and counts street taxis that cannot take a jek_rides order. `supply.status`: `ok` (measured, cars) | `none` (measured, none) | `unavailable` (OUR outage — show a retry, never "no cars") | `not_applicable` (this area's `fulfilment` is partner/fleet, so our own fleet is not the answer). `eta` is the road route to the NEAREST car, falling back to the same straight-line estimate the live ride's `remaining_route` uses and labelled `source: estimate`; each class routes its own nearest eligible car, with parallel four-second timeouts and one call per distinct driver. Classes sharing a car share its ETA. A failed route falls back from that car's own coordinates with eta_source: estimate and eta_confidence: low. Never answers 5xx for an outage. This reports supply, it does NOT authorise a booking — /ride/preflight stays the coverage authority. Cached 10s on the rounded request.

The pins the where-to map draws before anything is assigned: JEK's OWN drivers around a point, from the same `da_drivers` probe /ride/availability counts (online, approved, fix newer than 150s, inside the radius, not on a job) — with no routing call, so a map may poll it every 12s. Deliberately NOT /passenger/nearby, which proxies Wonder DA's taxis/nearby with partner credentials: that is the lane a JEK rider is handed down OUTSIDE Hong Kong, and it returns street taxis that cannot take a jek_rides order. `vehicles[]` is nearest first, capped at `limits.max_vehicles` (supply.count stays the true number); each `id` is a pseudonym that is stable across polls and rotates daily — never a driver id. `supply.status` as on /ride/availability: `ok` | `none` (measured, empty street) | `unavailable` (OUR outage — not an empty street, not cached) | `not_applicable` (this area's fulfilment is partner/fleet; somebody else's cars serve it). Never 5xx for an outage. Reports supply, does not authorise a booking. Cached 10s on the rounded request.

Server-side Google Directions proxy. Returns an encoded polyline plus distance (metres) and duration (seconds) for a pickup → destination pair. Used by the booking wizard so the browser never needs a Maps key.

Runs the free-text (or transcribed voice) wish through the analysis model with the route context. Returns feasibility, whether it is really a plain ride, clarification questions, estimated extra time/cost and a suggested tip range.

Recomputes a signed fare quote when the vehicle class or route changes after /api/v1/ride/wish-analysis, without re-running the language model. Wish facts sent by the client are clamped server-side, so a cheaper wish cannot be forced.

All admin dashboard reads/writes go through this endpoint instead of talking to the database directly. Table names are whitelisted server-side; every request is admin-gated.

Accepts a batch of contacts (name + phone(s) + optional emails), normalizes each phone to E.164 using the provided default_country (e.g. "852"), and upserts them into jek_user_contacts scoped to the caller. Safe to call repeatedly — duplicates are merged by (user_id, phone_e164).

Returns the caller's uploaded contacts. Each contact carries an on_jek flag computed by matching phone_e164 against the JEK user directory server-side (via SECURITY DEFINER — no direct DB read from the client).

Returns every active referral code the user owns plus the default one, each with invite.jek.app URL and WhatsApp/SMS share links. First call for a user lazily allocates a random 8-char default code (collision-safe).

Allocates a new random code owned by the caller. Useful for influencers or marketing campaigns that need to attribute installs per channel. Set make_default=true to promote it to the primary code.

Called by invite.jek.app to confirm an inbound ?ref=CODE is real before showing it to the visitor and setting the attribution cookie. Never returns the owner's identity.

Called by the invite.jek.app landing page whenever it loads with a valid ?ref=CODE. Increments the code's visit_count and records platform (ios/android/web), source, referrer and user-agent.

Returns every conversation the user is a member of, ordered by last_message_at. Each entry carries last_message_preview, unread_count, member list, and type (dm/group/agent/support).

Provide type='agent' for the auto-created JEK Assistant thread (idempotent — returns the existing one), user_id for a 1:1 DM with a JEK user, phone for a DM by phone number (creates the counterparty stub if needed), or type='group' with member_ids for a new group chat.

Returns the conversation, its members, and the most recent `limit` messages (default 50). Pass `before` (ISO timestamp) for pagination to older messages.

Set kind='text' (default) for plain text. For attachments upload via POST /api/v1/me/messaging/attachments first, then send kind='image'|'file'|'voice' with the returned path in attachments. Mentioning @jek in a non-agent conversation triggers a JEK Assistant reply from the fan-out job.

Fires a lightweight realtime event other members receive within ~200ms. Client should debounce — call at most once every 3 seconds while the user is actively typing.

Returns a one-shot signed URL you can PUT the raw file to directly (never rehashed through the Worker). Returns the storage path to include in the subsequent POST /messages call. Bucket is private — read access is signed on demand via GET /attachments?path=...

Cross-references the caller's uploaded contacts with jek_account_users to power the New Chat picker. Returns [{ user_id, name, phone }].

Browsers call this to obtain the VAPID applicationServerKey before subscribing to Web Push. Also returns the service worker path (/sw.js).

For web, pass { platform: 'web', endpoint, p256dh, auth } from PushSubscription.toJSON(). For native, pass { platform: 'ios' | 'android', expo_token } from expo-notifications' getExpoPushTokenAsync(). Upsert is de-duped by endpoint / expo_token so it's safe to call on every app start.

Thin proxy that forwards to https://main.bindo.co/svc/user/api/v2/signin/check with the same JSON body. Injects x-client-id / x-platform-id defaults when not provided. Returns whether the phone is already registered.

Forwards to main.bindo.co/svc/user/api/v2/otp/verify. On success (code=200 with an access_token), the user is upserted into public.profiles on the JEK App Supabase so the admin dashboard sees every sign-in.

Forwards to main.bindo.co/svc/user/api/v2/signup/completed. On success, the new user (including first/last name) is upserted into public.profiles.

Forwards to main.bindo.co/user/b2c/me. Requires X-USER-ACCESS-TOKEN header (the legacy access token returned from otp/verify).

Any path under /api/legacy/* is forwarded verbatim to https://main.bindo.co/<same-path> with the request body, query string, and non-hop headers intact. Supports GET, POST, PUT, PATCH, DELETE and OPTIONS (CORS is open).

Home, Work and custom places, in the rider's display order. `meta.max_places` is the ceiling. Each place carries the normalized `{ placeId, text, fullText, lat, lng, provider }` that /api/v1/geo/place answers with, so it can be booked without a second resolve.

The place is resolved and normalized server-side from `placeId` (or accepted as a dropped pin when `place` carries lat, lng and a name); raw display text alone is refused with 400 `invalid_place`, and an id the provider cannot resolve with 422 `unresolvable_place`. One Home and one Work per rider: a second is 409 `home_already_exists` / `work_already_exists`. `pickup_note` is private until the rider books from this place.

Edit label, pickup_note (null clears), type, sort_order or the place itself (placeId / place). Send the `version` you last read: a stale one is 409 `version_conflict` and nothing is written. The response carries the new version.

Soft delete, idempotent: a repeated delete answers the same `{ data: { id, deleted: true } }`. The place leaves future recommendations; historical trips are untouched.

Body `{ ids: [...] }` in the order to show. Places left out keep their relative order after the named ones. Answers the full list.

`meta` carries `max_contacts` (configurable, default 5), `supported_channels` (today `sms`) and `verification_delivery`: `simulated` on the staging fulfilment env (X-JEK-Env: staging; no message is sent and the platform's fixed test code confirms) or `unavailable` where no SMS provider exists yet.

The phone is normalized to E.164 (a bare local number is read as +852; send `default_country` to change that). Refused: an invalid number (400 `invalid_phone`), the rider's own number (400 `invalid_phone`), a number already saved (409 `duplicate_contact`), and one past the ceiling (409 `contact_limit_reached`). New contacts are `pending` until verified; nothing automated reaches them before that.

Conditional on `version` (409 `version_conflict` when stale). Changing `phone` resets `verification_status` to `pending` — the consent belonged to the old number.

Soft delete, idempotent. The contact stops receiving anything immediately; if it was the primary, nobody is promoted in its place.

Issues a 6-digit code valid for 10 minutes, at most once a minute per contact (429 `rate_limited`). 409 `already_verified` for a verified contact. 503 `notification_provider_unavailable` where no delivery exists (alpha/production today); on staging the send is simulated and `meta.delivery` says so.

200 with `meta.outcome` verified; 400 `invalid_code` (with `attempts_remaining`, 5 per code); 409 `verification_not_started`; 410 `verification_expired` when the code lapsed or the attempts ran out.

Zero or one primary per rider; the previous primary steps down. Idempotent.

`data.profile_image` is null when the caller has none in this app. The `url` is a signed, short-lived link into a private bucket — render it, do not store it; `expires_in` is its life in seconds, and re-reading this endpoint (or GET /api/v1/me, which carries the same object) mints a fresh one.

Send `{ image }` as a data URL or bare base64, or a multipart body with an `image` part — the same pair the licence scan takes, so a client already doing one needs nothing new. This is BOTH the upload and the edit: there is one current image per rider per app, so a second POST replaces the first and the old object is deleted. 201 when the rider had none, 200 when one was replaced (`data.replaced` says the same thing). The format is read off the bytes, never off the declared content type: JPEG, PNG and WebP are stored, and HEIC — what an iPhone hands over by default — is refused 415 `image_format_unsupported` with `detected` and `accepted`, because nothing but iOS can display it and this server has no way to transcode. Over 5 MB decoded is 413 `image_too_large` carrying `max_bytes`; bytes that are not an image at all are 400 `invalid_image`; no image in the body is 400 `image_required`.

The row and the stored object both go. Idempotent: a rider with no image answers 200 with `removed: false` rather than 404, so a retry over a flaky connection never has to tell the two apart. Only this app's image is removed — the same account's picture in the other app is untouched.

The quote counterpart to POST /api/v1/supplier/orders. Authenticates with the shared X-Internal-Token (a partner is a platform, not a signed-in rider) and answers in the caller's registered dialect — Wonder callers get {code,message,data:{quotes,batch_id}}, native callers get {data:{quotes,batch_id}}. Priced from the same rate card the booking uses; batch_id ties a later booking back to the fares it was offered. Quotes are honoured for 10 minutes. Distance/duration echo what the caller sent — this path does not geocode or route. The classes offered are the globally enabled ones NARROWED by this partner's allow list at /admin/ride/partners: a partner with no list is offered everything, one that is not sold a named class is answered unknown_class, and a list that leaves nothing answers 403 no_partner_classes (not 503 no_card, which means the rate card itself is empty).

Receives Wonder order events for M1OS payment links. Authenticated three ways: a Wonder-RSA-SHA256 signature over the exact body bytes (primary), the shared webhook secret, and an allow-listed callback path. Replays and unsigned bodies are refused. GET on the same path is a health probe.

Rides and wishes together, newest first. History is paged by an opaque keyset cursor: echo `next_cursor` back as `?cursor=` for the next page, and stop when it comes back null. `limit` defaults to 50 and caps at 100. `?active=1` answers only the orders still in flight and is deliberately NOT paged. A `cursor` this endpoint did not issue is refused with 400 `invalid_cursor` rather than silently restarting at the newest row.

Splat route that mirrors the legacy Flutter client's standard-ride calls onto the JEK backend; accepts the Wonder session in the body for legacy clients.