Ngamia API proxy

Route shape

An Express middleware mounted at /api/ngamia/v1 maps requests to {NGAMIA_API_BASE_URL}/v1/{path} and preserves the query string. It forwards the HTTP method that reaches it. A reconstructed upstream path must start with /v1/; otherwise the Music API returns 404.

The proxy forwards only Content-Type and Idempotency-Key request headers from the client. JSON and URL-encoded bodies are parsed with a 2 MB limit, and the original raw payload is retained for forwarding. It does not forward a browser Authorization header; authenticated forwarding is performed using the Ngamia session cookies. It preserves selected response headers: content-type, content-disposition, cache-control, x-request-id, x-generation-id, x-music-creation-id, and retry-after.

Authenticated proxy fetches use a 280-second timeout. The response body/status are not normalized into the local error envelope. When no session is available, the proxy returns 401 with {error:{message:...}}.

Public music exception

Only a GET whose upstream path exactly matches /v1/music/public/{id} or /v1/music/public/{id}/content bypasses the session. The Ngamia API must still confirm the creation is public. The current middleware’s match expression includes the query string, so adding a query parameter prevents the public bypass and sends the request through authenticated handling. Other reads, including private creation content, use the authenticated flow.

Upstream paths used by the web app

These are observed web application calls, not schemas defined by this repository:

The upstream API owns authorization rules, payload schema, response envelope, supported query values, billing effects, and status behavior for these resources. Consult the Ngamia API contract for definitive details.