Nyuchi API overview

The Nyuchi API is a single FastAPI gateway hosted at api.nyuchi.com. Every product surface is mounted under /v1/<name>/* and is backed by its own Supabase project, so each product can scale, isolate, and meter independently. A single Stytch-derived platform JWT authorises requests across every namespace.

Use this guide when you need to call a product surface from a frontend, a server-to-server integration, or a partner application.

Base URL and versioning

Environment	Base URL
Production	https://api.nyuchi.com
Local development	http://localhost:8080

All product endpoints live under the /v1 prefix. The API version is reported by GET / in the api_version field. Legacy /api/* paths from earlier releases no longer resolve—update existing clients to /v1/*.

Namespace map

Each namespace maps to a dedicated Supabase project.

Namespace	Database	Purpose
/v1/auth, /v1/identity, /v1/family, /v1/organization, /v1/api-keys, /v1/content, /v1/directory, /v1/places, /v1/travel, /v1/events, /v1/applications, /v1/ubuntu, /v1/pipeline, /v1/admin, /v1/search, /v1/media, /v1/couch, /v1/dashboard	nyuchi_platform_db	Identity, multi-tenancy, places, events, content, business directory, admin
/v1/commerce	mukoko_bushtrade_db	Products, offers, businesses, inquiries, scam reports
/v1/pay/wallet, /v1/pay/tokens, /v1/pay/gateway	nyuchi_pay_db	Wallets, token lifecycle, fiat on/off-ramps
/v1/logistics	nyuchi_logistics_db	Vehicles, bookings, drivers, locations
/v1/lingo	mukoko_lingo_db	Phrases, languages, study sessions, XP, progress
/v1/news	mukoko_news_db	Articles, journalists, organisations, engagement
/v1/weather	(reserved)	Placeholder until a weather backend is selected

Authentication

Every protected endpoint accepts the same platform JWT. Obtain a token from the Stytch-backed auth pipeline at /v1/auth/*, then send it on subsequent requests.

GET /v1/lingo/me/xp HTTP/1.1
Host: api.nyuchi.com
Authorization: Bearer <platform-jwt>

The same token works across every namespace. Some read endpoints accept anonymous calls (get_optional_user) and return public data; mutating endpoints require an authenticated caller (get_current_user).

Configuration status

GET / reports the gateway version and whether each product database is wired up. Use it to confirm what the deployed environment can serve.

curl https://api.nyuchi.com/

{
  "name": "Nyuchi API",
  "version": "4.1.0",
  "api_version": "v1",
  "namespaces": ["/v1/auth", "/v1/commerce", "/v1/pay", "..."],
  "product_dbs": {
    "commerce": true,
    "pay": false,
    "logistics": true,
    "lingo": true,
    "news": true
  }
}

A false entry means the gateway has no credentials for that database. Routers in that namespace return HTTP 503 at request time so the rest of the gateway keeps working.

Note

The pay namespace is configured but its schema is not yet provisioned. Endpoints that read or write data return HTTP 501 until the schema is deployed. Status endpoints under /v1/pay/status and the gateway root remain available.

Configuring product databases

The gateway reads one environment-variable triplet per database. Set them as Fly secrets before deploying.

# Platform DB (legacy names retained for backward compatibility)
SUPABASE_URL=https://<project>.supabase.co
SUPABASE_PUBLISHABLE_KEY=sb_publishable_...
SUPABASE_SECRET_KEY=sb_secret_...

# Per-product DBs — substitute COMMERCE / PAY / LOGISTICS / LINGO / NEWS
COMMERCE_SUPABASE_URL=https://<project>.supabase.co
COMMERCE_SUPABASE_PUBLISHABLE_KEY=sb_publishable_...
COMMERCE_SUPABASE_SECRET_KEY=sb_secret_...

Routers depend on the secret key; the publishable key is optional and only used for RLS-scoped clients.

Error handling

Status	Meaning
401 Unauthorized	Missing or invalid platform JWT on a protected endpoint.
404 Not Found	Resource does not exist in the namespace’s database.
501 Not Implemented	Endpoint exists but its underlying schema is not provisioned (currently /v1/pay/* and /v1/weather/forecast).
503 Service Unavailable	The product database for this namespace is not configured in the running environment.

Next steps

• Commerce API — BushTrade product, business, and inquiry endpoints.
• Pay API — wallet, token, and gateway sub-namespaces.
• Logistics API — vehicle bookings.
• Lingo API — language learning surface.
• News API — articles and engagement actions.
• Weather API — reserved namespace.