Routing engine

Rikaii routes each POST /v1/chat/completions request using a fixed evaluation order: an early BYOK routing branch when your request pins a catalog model and your workspace has routing enabled for that provider’s stored key; otherwise Dashboard rules (keywords, static mode, category-based primaries); then heuristic classification when rules do not decide. The goal is predictable behavior for integrators while optimizing cost when you opt in to automatic routing.

PAYG vs BYOK — what actually changes for developers

Both paths speak the same OpenAI-compatible JSON to you. The difference is whose credentials pay the provider and which spend rails apply:

Aspect	PAYG (platform-metered)	BYOK (bring your own key)
Upstream credential	Rikaii-managed pool for that provider	Your stored secret for that provider when routing is enabled and the route resolves to BYOK
Catalog & pricing	Routed model row uses Rikaii list wholesale + platform fee math for metering	You pay the vendor directly under your contract; Rikaii may still record metadata and apply plan rules where configured
Overage protection	Active when the workspace toggle is on—dynamic completion caps from remaining budget	Skipped for the budget-token cap path—BYOK routes are not budget-capped the same way. Please set overage protection on the respective providers' platform that you will be using.
Monthly spend / key credit guards	Enforced on metered retail totals	BYOK traffic does not consume the same platform wholesale bucket; guards focus on metered segments

Practical takeaway: If you need maximum spend predictability on shared keys, stay on metered catalog routes with overage protection and explicit max_tokens / max_completion_tokens in your client. If you need provider-native billing or custom enterprise deals, configure BYOK and enable routing for that provider.

Tier 1 — BYOK routing gate (not “always honor model”)

When your JSON body includes a non-empty model string, the gateway first resolves that identifier against the catalog and your BYOK configuration:

1. Catalog slug with BYOK routing active — If model matches an active catalog modelSlug and your account has BYOK routing enabled (“use my key”) for that row’s provider, the request is dispatched on your credential and keyword rules and heuristic auto-routing are skipped for this call. The pinned slug is the source of truth for dispatch and the response model field (gateway slug).

2. Catalog slug with BYOK routing off — If model matches the catalog but BYOK routing is not enabled for that provider (or you rely on platform keys), execution does not stop here: the gateway falls through to Tier 2 (keywords) and Tier 3 (heuristics / category rules) exactly like a request with no BYOK pin. Pinning model alone does not bypass smart routing unless BYOK routing is active for that provider.

3. BYOK-only catalog rows — Some SKUs are marked isByokOnly in GET /v1/models. Those require a valid BYOK key with routing enabled; otherwise the API returns 403 with error.code byok_required (see Errors).

4. Non-catalog identifiers — Custom upstream ids (for example namespaced OpenRouter-style ids) may be accepted when the gateway can infer the provider and your BYOK routing is active; unknown ids with BYOK partially configured can yield 400 with a descriptive message.

Configure BYOK in Dashboard → Settings; see BYOK integration.

Tier 2 — Keyword triggers (Dashboard rules)

If Tier 1 does not return a routing decision, the gateway evaluates user-defined keyword rules from your Dashboard configuration.

• Only the last user message in the messages array is scanned (the final message whose role is user).
• Rules are evaluated in persisted category order; within each category, keywords are tried in list order. The first substring match on the normalized last user message wins for that pass.
• Message content may be a string or structured content; rules apply to the text the platform extracts for matching.

Compared to Tier 3: keywords are explicit and deterministic. They override default heuristic picks whenever Tier 1 did not already lock the route. Use them for product names, internal codewords, or compliance-sensitive intents where you cannot rely on automatic classification.

Tier 3 — Heuristic classification and category rules

If Tier 2 does not match, Rikaii runs automatic classification on the conversation context and assigns internal intent categories, such as:

• Complex reasoning — multi-step analysis, math-heavy or abstract reasoning.
• Code generation — implementation, refactors, stack traces, developer tooling.
• Simple queries — short answers, classification, light rewriting.
• High volume — bulk or low-latency oriented workloads where economics dominate.

The platform then selects the most cost-effective eligible model for that category, subject to your workspace rules, provider availability, and catalog. If your Dashboard defines a rule for the mapped category, that rule’s primary (and optional fallback) is used.

Heuristic routing is opaque at the HTTP layer: you still send standard OpenAI-shaped JSON; you do not send category names in the request. Inspect the returned model field (gateway catalog slug) and usage when auditing behavior—see Chat completions.

Fallback and resilience

If the chosen primary upstream route hits a retryable failure, Rikaii may run a secondary path—either a fallback model from your Dashboard rules (common on PAYG) or a Safety Net retry on platform keys when you were on BYOK and have that option enabled. Full behavior (including streaming limits and BYOK-only restrictions) is documented in Fallback routing.

When a fallback succeeds on a non-streaming response, the HTTP response may include:

X-Rikaii-Fallback: true

See also Parameter sanitization for how request fields are normalized before dispatch.

Related

• Fallback routing
• BYOK integration
• Parameter sanitization
• Overage protection
• Rate limits
• Chat completions