Routing engine

Rikaii routes each POST /v1/chat/completions request to an upstream model according to a fixed three-tier hierarchy. Lower tiers run only when higher tiers do not apply. The goal is predictable behavior for integrators while optimizing cost when you opt in to automatic routing.

Tier 1 — BYOK bypass

When all of the following are true, Rikaii honors the model value in your request and does not apply keyword triggers or heuristic auto-routing for that call:

1. Your JSON body includes an explicit model string (OpenAI-compatible identifier).
2. Your workspace has configured Bring-your-own-key (BYOK) for the provider that serves that model.
3. The request is satisfied using that BYOK credential.

In this mode, the gateway treats your model as the source of truth for which upstream SKU to call. Configure BYOK in the Dashboard; see BYOK integration.

Tier 2 — Keyword triggers

If Tier 1 does not apply, 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).
• Matching is against your configured keywords; first match wins and selects the associated route.
• Message content may be a string or structured content; rules apply to the text the platform extracts for matching.

Use Tier 2 when you want deterministic routing for specific intents (for example product names or internal codewords) without hard-coding model IDs in application code.

Tier 3 — Heuristic classification

If neither Tier 1 nor Tier 2 applies, Rikaii runs automatic classification on the conversation context and assigns one of several 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.

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 response metadata such as the returned model identifier and usage when auditing behavior.

Fallback and resilience

If the chosen upstream route fails (timeouts, capacity errors, or similar), Rikaii may retry using fallback routes you configure in the Dashboard. When a fallback fulfills the request, the HTTP response may include:

X-Rikaii-Fallback: true

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

Related

• BYOK integration
• Parameter sanitization
• Rate limits
• Chat completions