Skip to content
Nyuchi Docs

API overview

The Nyuchi API is a single versioned HTTP gateway. Every endpoint lives under a /v1/<product>/* namespace backed by its own product database, so you can scale, isolate, and meter each product independently while keeping one base URL and one set of credentials.

Base URL

Section titled “Base URL”
Environment URL
Production https://api.nyuchi.com
Legacy host https://api.mukoko.com

Product namespaces

Section titled “Product namespaces”

Each namespace is backed by its own database. Endpoints in a namespace return 503 Service Unavailable when the underlying database is not configured for the current deployment, so you can detect availability with a single health check.

Namespace Purpose
/v1/auth, /v1/identity Sign-in, session, and person records
/v1/family, /v1/organization Household and org membership
/v1/places, /v1/events, /v1/directory Locations, calendar, and listings
/v1/content, /v1/media, /v1/search Articles, uploads, and search
/v1/travel, /v1/applications, /v1/ubuntu Travel bookings, applications, community
/v1/pipeline, /v1/dashboard, /v1/api-keys Internal tooling, dashboards, developer keys
/v1/commerce Products, offers, reviews, and inquiries
/v1/pay/wallet, /v1/pay/tokens, /v1/pay/gateway Wallets, tokens, and gateway transactions
/v1/logistics Booking drafts and shipments
/v1/lingo Translation and language tooling
/v1/news News articles and feeds
/v1/weather Weather forecasts (reserved)

Authentication

Section titled “Authentication”

Every authenticated request must send a platform JWT in the Authorization header:

Terminal window
curl https://api.nyuchi.com/v1/auth/me \
  -H "Authorization: Bearer $ACCESS_TOKEN"

All user authentication is handled by WorkOS AuthKit: the JWT is minted by /v1/auth/workos/* after AuthKit sign-in. See Authentication for the full flow.

For programmatic and server-to-server access, use an API key instead—a client ID and secret pairing created and managed in the console. See API keys.

Some namespaces are gated by an additional shared secret:

  • /v1/admin/* and /v1/pay/* require an X-Internal-Key header that matches the backend’s INTERNAL_API_KEY. These endpoints are intended for first-party staff tooling and never reach the public browser. If you need a customer-facing wallet or admin surface, call the console’s same-origin proxy routes instead—they inject the key on the server side.

Detecting unconfigured products

Section titled “Detecting unconfigured products”

A 503 response from a product namespace means the database for that product is not configured in the current environment. The error body has a stable shape so you can branch on it without parsing prose:

{
  "detail": "commerce database is not configured"
}

Treat 503 as “feature flag off” rather than as a transient outage—retrying will not help until the operator wires up the database.

Health and discovery

Section titled “Health and discovery”

GET / returns a manifest of every configured product database, the API version, and the public release name (Nyuchi API, currently v4.1.0). Use it as a lightweight readiness probe and as a way to discover which namespaces are live in the environment you are targeting.

Next steps

Section titled “Next steps”