Skip to main content
Use the routing object to make a request faster, more reliable, cheaper, or more exact than NagaAI’s default choice. It’s a NagaAI field, so the OpenAI and Anthropic APIs don’t have it.

Where it appears

You send the object as the top-level routing field of a request body:
  • strategy, max_price and precision: POST /v1/responses, POST /v1/chat/completions, and POST /v1/messages.
  • max_price and precision: the image, video, audio, embeddings, moderation, and rerank endpoints. In a form, the OpenAI SDKs send precision as repeated routing[precision][] parts.
The object is optional. If you omit it, NagaAI orders the providers by price and its own strategy, with no price limit, and in any precision.

Attributes

enum<string>
The order in which NagaAI tries providers at the same price. Chat endpoints only; see Strategy values.If omitted, NagaAI uses the x-naga-routing-strategy header, then the key’s default, then the workspace’s, then its own choice.
object
The most one unit of each named meter may cost, in credits. Only providers at or below every cap serve the request; see Meters.If omitted, the request has no price limit.
array<enum<string>>
The weight precisions the request may be served in, at least one. Only providers that publish one of the listed precisions serve the request; a provider that publishes none never does. See Precision values.If omitted, the request may be served in any precision, including an unpublished one.

Strategy values

strategy takes one of the following values. Values are case-sensitive.

Precision values

Each item of precision is one of int4, int8, fp4, mxfp4, nvfp4, fp6, fp8, mxfp8, fp16, bf16 and fp32. The precisions a model’s providers publish are its precision in GET /v1/models.

Meters

Each key of max_price is a meter from the model’s pricing in GET /v1/models. Each value is a non-negative decimal, as a string such as "0.000005" or a number. A meter that the model doesn’t price is ignored, so one cap can serve several models.

Example object

Responses and Chat Completions also take OpenAI’s service_tier. Only flex changes routing: it uses only providers at the model’s base price. auto, default, scale and priority route as default, and an unknown value isn’t an error. Messages has no service_tier.

Errors

A mistake in routing fails with 400 and type invalid_request_error before NagaAI tries a provider, so it costs nothing. A JSON body’s message ends with the position in the body, such as at line 1 column 54; the table leaves it out. A form request, such as image edits and audio uploads, reports every mistake under body.routing: , with no position. When the request is valid but no provider of the model or of any fallback model is within the limit, the request fails with 400 invalid_request_error:
When no provider of the model or of any fallback model publishes a precision that routing.precision lists, the error names the field in param. Messages has no param in its error shape, so there the message alone says it:

See also