API Reference

Naga Bonar Mesh API

Stream tokens from the fastest healthy model provider over a single edge-native endpoint.

Overview

The mesh exposes one streaming endpoint. Send a prompt with route:"auto" and Naga Bonar scores providers by latency, cost and quality, then streams tokens back over SSE. Base URL:

BASE https://api.nagabonar.dev

Authentication

Every request needs a scoped key with its own budget. Pass it as a bearer token.

Authorization: Bearer nb-live-***

Keys carry a hard spend budget. When the budget is hit, the mesh returns 402 budget_exceeded instead of overspending.

Quickstart

# stream a completion, auto-routed
curl -N https://api.nagabonar.dev/v1/stream \
  -H "Authorization: Bearer nb-live-***" \
  -H "Content-Type: application/json" \
  -d '{ "route":"auto", "prompt":"explain the mesh", "budget":0.02 }'

POST /v1/stream

Opens a server-sent event stream of tokens from the selected provider.

Body parameters

Field	Type	Description
route	`string`	`"auto"` or a pinned provider id. Auto picks the fastest healthy route.
prompt	`string`	The input prompt. Use `messages` for chat format.
budget	`number`	Max spend in USD for this request. Mesh stops before exceeding it.
region	`string`	Optional. Pin the edge region, e.g. `"sea"` or `"eu"`.
cache	`bool`	Enable semantic cache for repeat prompts. Default `true`.

Routing modes

Mode	Behavior
auto	Score latency + cost + quality, fail over on error.
cheapest	Lowest cost healthy provider.
fastest	Lowest p50 first-token latency.
pinned	Force a single provider id.

Stream events

event: route   // chosen provider + region
data:  {"provider":"provider-3","region":"sea","p50":38}

event: token
data:  {"token":"Naga"}

event: done
data:  {"tokens":128,"cost":0.004,"ms":410}

SDK install

# python
pip install nagabonar

# node
npm i @nagabonar/mesh

Errors

Code	Meaning
401	`invalid_key` — missing or bad bearer token.
402	`budget_exceeded` — request budget reached.
429	`rate_limited` — per-key rate limit hit.
503	`no_healthy_route` — all providers down for this route.

// Illustrative demo. Endpoints do not resolve.