A Kotlin client for an API gateway can be a thin wrapper around blocking HTTP calls, with a coroutine adapter bolted on. The nRouter Kotlin guide goes the other way: the SDK is coroutines-first from the start — suspend functions for calls, a cold Flow for streaming, and typed error subclasses you can branch on.
Full guide: https://nrouter.ai/docs/sdks/kotlin
Setup
The guide publishes the artifact to your local Maven cache (./gradlew clean check publishToMavenLocal), then it's a normal Gradle dependency:
dependencies { implementation("ai.nrouter:nrouter-sdk-kotlin:3.1.2") } NRouter() reads NROUTER_API_KEY from the environment, targets https://api.nrouter.ai/v1, and dispatches on Dispatchers.IO, so calls don't block your caller's context. (For Android apps, the guide points to the separate nrouter-sdk-android artifact.)
A call, and what comes back
suspend fun main() { val client = NRouter() val result = client.chatCompletions( JSONObject() .put("model", "nrouter/auto") .put("messages", listOf(mapOf("role" to "user", "content" to "Hello!"))) .put("nrouter_optimize", "balanced") ) val content = result.body.getJSONArray("choices") .getJSONObject(0).getJSONObject("message").getString("content") println(content) println("Request ID: ${result.meta.requestId}") } Two things worth noticing. The routing preference rides in the payload: "nrouter/auto" plus "nrouter_optimize" (quality, balanced or cost), with "nrouter_cost_band" (low, mid, high) available under cost. And the response carries .meta extracted from the gateway's x-nr-* headers, so request ID and cost metadata arrive as typed fields instead of header strings you parse yourself.
Streaming is a cold Flow — nothing moves until you collect:
client.messagesStream( JSONObject() .put("model", "nrouter/auto") .put("messages", listOf(mapOf("role" to "user", "content" to "Hello!"))) ).collect { chunk -> print(chunk.delta) } Cold matters here: the request starts on collection and stops when the collector goes away, which is exactly the lifecycle behaviour you want in a view model or a Ktor handler.
Errors you can branch on
Gateway refusals map to subclasses of NRouterError: Request (400, including cost_band_unsatisfiable), GuardrailBlocked (400), Authentication (401), Credit (402), RateLimit (429) and Service (503). The detail that makes this practical is isRetryable — true for RateLimit, Service and Transport — so a retry policy is one when branch instead of a table of status codes maintained by hand.
That's the whole shape: a JVM client that treats coroutines as the default rather than an add-on, and lets the gateway carry routing, budgets and guardrails behind one key. The guide has the full walkthrough: https://nrouter.ai/docs/sdks/kotlin

![[Herdr in Practice] Build Your Own Herdr Mod: Create a "Pending Review" Queue with Labels to Instantly Track Unread Reports](https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Flasxwu5u1is3pu1fn6gi.png)