cd /news/ai-tools/coroutines-first-notes-on-nrouter-s-… · home › topics › ai-tools › article
[ARTICLE · art-172544] src=dev.to ↗ pub= topic=ai-tools verified=true sentiment=↑ positive

Coroutines first: notes on nRouter's Kotlin SDK

NRouter released a coroutines-first Kotlin SDK (ai.nrouter:nrouter-sdk-kotlin:3.1.2) for its API gateway, using suspend functions for calls and a cold Flow for streaming responses. The client reads NROUTER_API_KEY from the environment, dispatches on Dispatchers.IO, exposes gateway routing preferences like nrouter_optimize and nrouter_cost_band in the request payload, and surfaces x-nr-* header metadata as typed fields. Gateway refusals map to typed NRouterError subclasses with an isRetryable flag that is true for RateLimit, Service and Transport errors.

key takeaway

The nRouter Kotlin SDK makes streaming a cold Flow that starts on collection and cancels with the collector, and marks RateLimit, Service and Transport errors as retryable via isRetryable so retry policy is a single when branch.

by read2 min views1 publishedNov 19, 2026

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

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.)

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.

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

── more in #ai-tools 4 stories · sorted by recency
── more on @nrouter 3 stories trending now
sponsored brought to you by zahid.host 4,200+ EU-deployed projects
reading about agents? ship yours in a single git push.

Run your AI side-project on zahid.host

EU-based hosting, git-push deploys, automatic HTTPS, no cold starts. Free tier with a custom domain — perfect for shipping the agent you just read about.

$git push zahid main
→ Live at https://your-agent.zahid.host ✓
Get free account → Pricing
from €0/mo · no card required
LIVE [news/coroutines-first-not…] indexed:0 read:2min 2026-11-19 · —