nyuchi · mintlify · May 8, 2026
diff --git a/docs.json b/docs.json
@@ -142,6 +142,20 @@
               "integrations/webhooks/event-types",
               "integrations/webhooks/retry-policies"
             ]
+          },
+          {
+            "group": "Nyuchi API",
+            "icon": "globe",
+            "expanded": true,
+            "pages": [
+              "integrations/nyuchi-api/overview",
+              "integrations/nyuchi-api/commerce",
+              "integrations/nyuchi-api/pay",
+              "integrations/nyuchi-api/logistics",
+              "integrations/nyuchi-api/lingo",
+              "integrations/nyuchi-api/news",
+              "integrations/nyuchi-api/weather"
+            ]
           }
         ]
       }

diff --git a/integrations/nyuchi-api/commerce.mdx b/integrations/nyuchi-api/commerce.mdx
@@ -0,0 +1,81 @@
+---
+title: Commerce API
+description: Endpoints for BushTrade products, businesses, offers, inquiries, and scam reports.
+---
+
+The commerce namespace exposes the BushTrade product surface—local businesses, products and offers, buyer inquiries, and scam reports. It is backed by the `mukoko_bushtrade_db` Supabase project.
+
+Use these endpoints when building consumer or partner experiences that browse listings, accept inquiries, or surface trust signals.
+
+**Base path:** `/v1/commerce`
+
+## Endpoints
+
+| Method | Path | Auth | Purpose |
+|--------|------|------|---------|
+| `GET` | `/v1/commerce/products` | Optional | List products. Supports `business_id`, `limit`, `offset`. |
+| `GET` | `/v1/commerce/products/{product_id}` | Optional | Fetch a single product. |
+| `POST` | `/v1/commerce/products` | Required | Create a product owned by the caller. |
+| `GET` | `/v1/commerce/businesses` | Optional | List local businesses. |
+| `GET` | `/v1/commerce/businesses/{business_id}` | Optional | Fetch a single business. |
+| `GET` | `/v1/commerce/offers` | Optional | List offers. Supports `product_id`. |
+| `POST` | `/v1/commerce/inquiries` | Required | Send an inquiry against a product or business. |
+| `POST` | `/v1/commerce/scam-reports` | Required | Report a product, business, or offer for review. |
+
+## List products
+
+```bash
+curl "https://api.nyuchi.com/v1/commerce/products?limit=20"
+```
+
+```json
+{
+  "data": [
+    { "id": "p_01", "name": "Honey 500g", "price": 4.5, "currency": "USD", "business_id": "b_42" }
+  ],
+  "count": 1
+}
+```
+
+## Create a product
+
+```bash
+curl -X POST https://api.nyuchi.com/v1/commerce/products \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Honey 500g",
+    "description": "Wild forest honey, harvested in Mashonaland.",
+    "price": 4.5,
+    "currency": "USD",
+    "business_id": "b_42"
+  }'
+```
+
+The caller's identity is recorded as `created_by` automatically.
+
+## Submit an inquiry
+
+Inquiries always belong to the authenticated person.
+
+```bash
+curl -X POST https://api.nyuchi.com/v1/commerce/inquiries \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{ "product_id": "p_01", "message": "Do you ship to Bulawayo?" }'
+```
+
+## Report a scam
+
+`target_type` must be `product`, `business`, or `offer`. The reporter is recorded automatically.
+
+```bash
+curl -X POST https://api.nyuchi.com/v1/commerce/scam-reports \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{ "target_type": "product", "target_id": "p_01", "reason": "Listed at impossible price." }'
+```
+
+<Warning>
+  Row-level security is currently disabled on `commerce.*` tables. The router enforces auth in code today; database policies will replace that enforcement before public release. Treat write endpoints as authenticated-only and do not expose service keys to clients.
+</Warning>
diff --git a/integrations/nyuchi-api/lingo.mdx b/integrations/nyuchi-api/lingo.mdx
@@ -0,0 +1,73 @@
+---
+title: Lingo API
+description: Languages, phrases, study sessions, and learner progress for Mukoko Lingo.
+---
+
+The lingo namespace serves the Mukoko Lingo learning surface—languages, phrases and translations, learner progress, XP, and study session logging. It is backed by the `mukoko_lingo_db` Supabase project.
+
+Use these endpoints when building learner-facing experiences or analytics tools that read learner progress.
+
+**Base path:** `/v1/lingo`
+
+## Endpoints
+
+| Method | Path | Auth | Purpose |
+|--------|------|------|---------|
+| `GET` | `/v1/lingo/languages` | Optional | List supported languages. |
+| `GET` | `/v1/lingo/phrases` | Optional | List phrases. Supports `language`, `limit`, `offset`. |
+| `GET` | `/v1/lingo/phrases/{phrase_id}` | Optional | Fetch a phrase with its translations. |
+| `GET` | `/v1/lingo/me/progress` | Required | Return phrase progress for the caller. |
+| `GET` | `/v1/lingo/me/xp` | Required | Return XP and level for the caller. |
+| `POST` | `/v1/lingo/me/study-sessions` | Required | Log a study session for the caller. |
+
+## Browse languages
+
+```bash
+curl https://api.nyuchi.com/v1/lingo/languages
+```
+
+```json
+{
+  "data": [
+    { "code": "sn", "name": "Shona" },
+    { "code": "nd", "name": "Ndebele" }
+  ],
+  "count": 2
+}
+```
+
+## Read a phrase with translations
+
+```bash
+curl https://api.nyuchi.com/v1/lingo/phrases/phr_01
+```
+
+```json
+{
+  "id": "phr_01",
+  "text": "Mangwanani",
+  "translation": [
+    { "language_code": "en", "text": "Good morning" }
+  ]
+}
+```
+
+## Log a study session
+
+The session is recorded against the authenticated learner.
+
+```bash
+curl -X POST https://api.nyuchi.com/v1/lingo/me/study-sessions \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "duration_seconds": 600,
+    "phrases_seen": 24,
+    "phrases_correct": 18,
+    "language_code": "sn"
+  }'
+```
+
+<Note>
+  Phrase analytics tables (views, engagement, recommendations, stats caches) are populated by the upstream streaming pipeline. The lingo router is read-only for those tables; submit study sessions through `POST /v1/lingo/me/study-sessions` instead of writing to analytics tables directly.
+</Note>
diff --git a/integrations/nyuchi-api/logistics.mdx b/integrations/nyuchi-api/logistics.mdx
@@ -0,0 +1,63 @@
+---
+title: Logistics API
+description: Vehicle, booking, driver, and location endpoints backed by nyuchi_logistics_db.
+---
+
+The logistics namespace serves the Nyuchi vehicle bookings backend. It exposes vehicles, bookings, drivers, and pickup or drop-off locations from the `nyuchi_logistics_db` Supabase project.
+
+Use these endpoints to power booking flows in consumer apps and partner integrations.
+
+**Base path:** `/v1/logistics`
+
+## Endpoints
+
+| Method | Path | Auth | Purpose |
+|--------|------|------|---------|
+| `GET` | `/v1/logistics/vehicles` | Optional | List vehicles. Supports `available`, `limit`, `offset`. |
+| `GET` | `/v1/logistics/vehicles/{vehicle_id}` | Optional | Fetch a single vehicle. |
+| `POST` | `/v1/logistics/bookings` | Required | Create a booking for the calling customer. |
+| `GET` | `/v1/logistics/bookings` | Required | List bookings owned by the caller. |
+| `GET` | `/v1/logistics/bookings/{booking_id}` | Required | Fetch a booking owned by the caller. |
+| `GET` | `/v1/logistics/locations` | Optional | List pickup and drop-off locations. |
+
+## Find an available vehicle
+
+```bash
+curl "https://api.nyuchi.com/v1/logistics/vehicles?available=true&limit=10"
+```
+
+```json
+{
+  "data": [
+    { "id": "v_01", "make": "Toyota", "model": "Hilux", "is_available": true }
+  ],
+  "count": 1
+}
+```
+
+## Create a booking
+
+The booking is automatically scoped to the authenticated caller via `customer_id`.
+
+```bash
+curl -X POST https://api.nyuchi.com/v1/logistics/bookings \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "vehicle_id": "v_01",
+    "pickup_location_id": "loc_jhb",
+    "dropoff_location_id": "loc_hre",
+    "pickup_at": "2026-06-01T08:00:00Z",
+    "return_at": "2026-06-05T18:00:00Z",
+    "notes": "Long-haul rental, second driver included."
+  }'
+```
+
+## List my bookings
+
+`GET /v1/logistics/bookings` only returns rows owned by the caller. Use `limit` and `offset` for pagination.
+
+```bash
+curl "https://api.nyuchi.com/v1/logistics/bookings?limit=20" \
+  -H "Authorization: Bearer $TOKEN"
+```
diff --git a/integrations/nyuchi-api/news.mdx b/integrations/nyuchi-api/news.mdx
@@ -0,0 +1,60 @@
+---
+title: News API
+description: Articles, journalists, organisations, and engagement actions for the Mukoko news surface.
+---
+
+The news namespace exposes the Mukoko news read surface—articles, journalists, and media organisations—plus a small write surface for engagement actions (like, bookmark, comment, follow). It is backed by the `mukoko_news_db` Supabase project.
+
+Articles and metadata are scored and curated upstream. The router serves the curated read surface to consumer apps and accepts engagement events from authenticated readers.
+
+**Base path:** `/v1/news`
+
+## Endpoints
+
+| Method | Path | Auth | Purpose |
+|--------|------|------|---------|
+| `GET` | `/v1/news/articles` | Optional | List articles. Supports `organization_id`, `journalist_id`, `limit`, `offset`. |
+| `GET` | `/v1/news/articles/{article_id}` | Optional | Fetch a single article. |
+| `GET` | `/v1/news/organizations` | Optional | List media organisations. |
+| `GET` | `/v1/news/journalists` | Optional | List journalists. Supports `organization_id`. |
+| `POST` | `/v1/news/articles/{article_id}/like` | Required | Like an article (idempotent upsert). |
+| `POST` | `/v1/news/articles/{article_id}/bookmark` | Required | Bookmark an article (idempotent upsert). |
+| `POST` | `/v1/news/comments` | Required | Post a comment on an article. Supports threaded replies via `parent_id`. |
+| `POST` | `/v1/news/journalists/{journalist_id}/follow` | Required | Follow a journalist. |
+| `POST` | `/v1/news/organizations/{organization_id}/follow` | Required | Follow a media organisation. |
+
+## List recent articles
+
+Articles are ordered by `published_at` descending.
+
+```bash
+curl "https://api.nyuchi.com/v1/news/articles?limit=10"
+```
+
+## Like an article
+
+Like, bookmark, and follow endpoints are idempotent—calling them twice is safe. The caller's identity is recorded automatically.
+
+```bash
+curl -X POST https://api.nyuchi.com/v1/news/articles/art_01/like \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+## Post a comment
+
+```bash
+curl -X POST https://api.nyuchi.com/v1/news/comments \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "article_id": "art_01",
+    "text": "Great reporting on this story.",
+    "parent_id": null
+  }'
+```
+
+Set `parent_id` to a comment ID to post a threaded reply.
+
+<Warning>
+  Several `news.*` tables have row-level security disabled. The router enforces auth in code on engagement endpoints; database policies will replace that enforcement before public release.
+</Warning>