JSON API

Calling capabilities over HTTP, and the other routes.

This page starts with docs/api.md, the API's own guide, as it stands in the repository. The reference after it is generated from the handler (apps/web/lib/api/handler.ts), the list of what is offered (apps/web/lib/api/exposed.ts) and the route files, so it cannot disagree with them; a test checks the guide's status table against the handler.

The backend's public surface for a native app (or any client that is not the web app's own pages). It runs the same capabilities the pages run, through the same executor, so every permission, refusal, audit entry and idempotency rule is the same.

• Route: apps/web/app/api/v1/capabilities/[name]/route.ts, handling in apps/web/lib/api/handler.ts.
• Which capabilities are offered: apps/web/lib/api/exposed.ts. A test fails when a new capability is neither offered nor kept off with a reason.
• Tests: apps/web/lib/api/handler.test.ts (fake platform) and apps/web/lib/api/flow.test.ts (the real platform over SQLite: sign-in, apply and approve through the route's handlers).

Calling a capability

POST /api/v1/capabilities/<name>
Content-Type: application/json
Authorization: Bearer <session token>      (once signed in)
Idempotency-Key: <8 to 128 characters>     (for a command)

<the capability's input, as a JSON object>

A query (a read) that takes no input may also be fetched with GET /api/v1/capabilities/<name>. Input never goes in the URL: request URLs are kept in Workers invocation logs and in proxy and client logs, so a GET with ?input= is refused with 400 api_input_in_url, and a query with input is sent by POST like a command (without an Idempotency-Key). GET on a command is refused with 405 and Allow: POST. An empty POST body means {}.

Every answer is JSON and is sent with Cache-Control: no-store:

{ "ok": true, "value": { "...": "..." } }
{ "ok": false, "refusal": { "code": "already_applied", "message": "…" } }

The message is the catalogue's text for the code (the API's own wording from apiErrors in apps/web/messages/*/api.json where the page's wording would not fit an app, else the shared errors text), in the language of the Accept-Language header (Chinese when neither language is asked for). Show message to the person and branch on code. Inputs and values are as defined in each capability in packages/core/src/capabilities/.

Status codes

Who is asking

• Bearer token: Authorization: Bearer <token>, the token from auth.verifyCode. No origin check is made: a browser never sends this header on its own, so another site cannot borrow it. A bearer header that is present must be valid; a lapsed one is answered 401 api_session_invalid, never treated as a visitor.
• Session cookie: the web app's own session cookie, for the app's pages. A cookie request must come from this app's own origin: an Origin header naming another origin, or Sec-Fetch-Site: cross-site, is refused with 403 api_cross_origin, the same check the other API routes make. A stale cookie counts as no session.
• Neither: a visitor; public capabilities run, others answer 401 unauthenticated.
• Platform operators are turned away. A session belonging to an operator (bearer or cookie) is refused with 403 api_operator_web_only for everything except auth.signOut, and when an operator signs in through auth.verifyCode the new session is revoked at once and no token is returned. Many member and admin capabilities give an operator platform-wide reach (completing an account erasure, appointing admins of any chamber, branding, moderation); that reach stays in the web admin.

The API never sets or clears a cookie, and sends no CORS headers: it is for native apps and the app's own pages, so a page on another origin cannot read its answers. (In pnpm dev, vinext's own development origin check answers a cross-origin request with a plain 403 Forbidden before the API sees it.)

The privacy notice

As on the pages, a signed-in person must have accepted the current privacy notice before member and admin capabilities run. Until then they are refused with 403 api_consent_required, and the refusal carries the version to accept:

{ "ok": false, "refusal": { "code": "api_consent_required", "message": "…", "noticeVersion": "2026-11-draft-4",
  "notice": { "ms": { "language": "Bahasa Malaysia", "title": "…", "paragraphs": ["…"] },
              "en": { "language": "English", "title": "…", "paragraphs": ["…"] } } } }

Show notice (both languages, whatever the interface language, as on /zh/consent), then call consent.accept with {"locale": "zh"|"en"}. The server records acceptance of the version it serves; a noticeVersion the app sends is ignored, so an old build cannot record a version that was never shown. Allowed before acceptance: auth.*, consent.accept, dataRequest.create, dataRequest.listMine, export.mine, and every public capability. auth.whoami returns consentedNoticeVersion.

Idempotency

A command (or job) needs an Idempotency-Key, which becomes the operation id. Generate one per intended action (a UUID) and reuse it when retrying that action after a timeout: the retry is answered with the recorded result and nothing happens twice. The same key with a different input or person is refused with 409 operation_conflict. A missing key is 400 operation_id_required. Queries ignore the header.

Commands whose result holds a secret (auth.verifyCode, auth.rotateSession, export.mine) never store their result: a retry under the same key is refused with 409 operation_already_completed and never returns the token again. If that happens after a lost response, start again with a new code (or, for rotation, sign in again).

Signing in

1. Ask for a code. The email carries the brand of the address the API is called on.

   POST /api/v1/capabilities/auth.requestCode
   Idempotency-Key: 6f1c…
   {"email": "mei@example.com", "locale": "zh"}
   → 200 {"ok": true, "value": {"sent": true}}

2. Check the code; the value is the session token, to keep in the device's secure storage.

   POST /api/v1/capabilities/auth.verifyCode
   Idempotency-Key: 0b9e…
   {"email": "mei@example.com", "code": "123456"}
   → 200 {"ok": true, "value": {"token": "…"}}

3. Who am I (also tells the app when to rotate):

   GET /api/v1/capabilities/auth.whoami
   Authorization: Bearer <token>
   → 200 {"ok": true, "value": {"userId": "…", "email": "mei@example.com", "consentedNoticeVersion": null, "rotationDue": false, …}}

   auth.whoami and auth.rotateSession take their token from the bearer header when the body leaves it out. Never put a token in a URL.

4. When rotationDue is true, swap the token: POST auth.rotateSession {} with the current token as the bearer header returns {"token": "<new>"}, and the old one stops working.

5. Sign out: POST auth.signOut {"everywhere": false} with the bearer token revokes this device's session (and its push subscriptions); {"everywhere": true} revokes every session. The token then answers 401 api_session_invalid.

Sign-in is guarded as the sign-in page is (apps/web/lib/security/limits.ts): per network and per address each minute, and, once a network has made several attempts in fifteen minutes, a Turnstile challenge. Without a token the call is refused with 403 challenge_required, and the refusal carries the Turnstile siteKey. The app shows the Turnstile widget with that key in a WebView whose page is loaded with the app's host as its base URL (the widget only runs on hostnames the site key allows), takes the token the widget's callback gives, and repeats the call with it in the CF-Turnstile-Response header. The core still limits codes per address and guesses per code.

Applying and approving

POST /api/v1/capabilities/consent.accept
Authorization: Bearer <token>
Idempotency-Key: …
{"locale": "en"}

GET  /api/v1/capabilities/committee.listOpen
POST /api/v1/capabilities/application.submit
{"committeeId": "…", "branchId": "…", "fullName": "Tan Mei Ling", "phone": "+60 12-345 6789",
 "company": "Sample Sdn Bhd", "position": "Director", "industry": "Trading", "locale": "en"}
→ 200 {"ok": true, "value": {"id": "…", "status": "submitted", …}}

The committee's Exco admin (or a branch or chamber admin above it):

POST /api/v1/capabilities/application.queue     {"unitId": "<committee id>"}
POST /api/v1/capabilities/application.approve   {"applicationId": "…", "note": "Welcome."}
POST /api/v1/capabilities/application.decline   {"applicationId": "…", "note": "…"}

Anyone else is answered 403 forbidden.

Which capabilities are offered

Every member and admin capability, and sign-in, for anyone who is not a platform operator (operator sessions are refused, above). Kept off, with the reason in exposed.ts:

• Platform-operator capabilities (chamber.create, chamber.list, audit.list, operations.health, news.* sources and jobs, host.*, dataRequest.listAll, support.viewChamber, outbox.deliver, digest.assemble, digest.sendEmails, eventNotice.send): operator work stays in the web admin, where support access asks for and shows its reason. Operator sessions are kept off long-lived app tokens by refusing them, not by this list alone.
• Raw image bytes (profile.setPhoto, brand.setLogo, eventPhoto.upload, and the readers profile.photo, brand.logo, eventPhoto.file, eventPhoto.showcaseFile): JSON cannot carry them. Uploads go through /api/uploads/* and photos are served from /photos/…, /event-photos/… and /showcase-photos/…. These use the session cookie today; a native app needs bearer support added there.

Limits

• Every call draws on the edge's per-network allowance, API_LIMIT (worker.ts), answered 429 rate_limited with Retry-After: 60.
• auth.requestCode and auth.verifyCode are guarded as above.
• import.prepare, which takes a CSV file, also draws on the network's upload allowance (UPLOAD_LIMIT), answered 429 upload_rate_limited.

Examples

API=https://chambers.example.com/api/v1/capabilities

curl -s "$API/auth.requestCode" -H 'content-type: application/json' \
  -H "idempotency-key: $(uuidgen)" -d '{"email":"mei@example.com","locale":"en"}'

TOKEN=$(curl -s "$API/auth.verifyCode" -H 'content-type: application/json' \
  -H "idempotency-key: $(uuidgen)" -d '{"email":"mei@example.com","code":"123456"}' | jq -r .value.token)

curl -s "$API/membership.mine" -H "authorization: Bearer $TOKEN" -H 'accept-language: zh'

curl -s "$API/auth.signOut" -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -H "idempotency-key: $(uuidgen)" -d '{"everywhere":false}'

Worked examples

API is the capabilities address, such as https://chambers.example.com/api/v1/capabilities (a chamber's own address; production is served at chambers.whymelabs.com), and TOKEN the session token from auth.verifyCode.

A query with input, by POST

Input never travels in the URL. A query that takes input is sent by POST, without an Idempotency-Key.

curl -s "$API/event.view" \
  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"eventId":"<event id>"}'

Retrying a command safely

Make one key per intended action and reuse it on retry. The second call is answered from the operation record; nothing happens twice.

KEY=$(uuidgen)
curl -s "$API/registration.register" -H "authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' -H "idempotency-key: $KEY" -d '{"eventId":"<event id>","guests":[],"locale":"en"}'
# The connection dropped? Send the same request with the same key:
curl -s "$API/registration.register" -H "authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' -H "idempotency-key: $KEY" -d '{"eventId":"<event id>","guests":[],"locale":"en"}'

The privacy notice gate

A member capability called before the current notice is accepted answers 403 with the notice to show:

curl -s "$API/membership.mine" -H "authorization: Bearer $TOKEN"
# → {"ok":false,"refusal":{"code":"api_consent_required","message":"Read and accept the privacy notice before continuing.","noticeVersion":"…","notice":{…}}}

curl -s "$API/consent.accept" -H "authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' -H "idempotency-key: $(uuidgen)" -d '{"locale":"en"}'

An error, as a client sees it

HTTP/1.1 422
cache-control: no-store
content-type: application/json

{"ok":false,"refusal":{"code":"already_applied","message":"You already have an application waiting for this committee."}}

Status codes, from the handler

The API's refusal codes and messages

The English text an app receives for each general code (Chinese is sent when the request asks for it). A capability's own codes, with their messages, are listed with each capability in the reference.

Offered capabilities

154 capabilities, every member and admin capability and sign-in. A query may be fetched by GET when it takes no input; every other call is a POST.

Kept off the API

Every route under /api

Besides the capability endpoint, these routes serve the web app's own pages; the JSON API's bearer tokens do not reach them yet. Who each serves is read from what its handler checks: public routes check neither the session nor the origin; cookie routes read the session cookie and answer by the viewer's rights; the uploads, push, check-in and export routes also refuse a request from another origin.

Other routes

Routes outside /api: images served with the viewer's rights checked on every request, the chamber's logo and icon, the manifest, and the bare address.

The pages themselves are listed in the page map.