Concepts

Routes and tokens

A route is the unit of policy in AdaptiveAPI. It binds an upstream service, a default language pair, a translator backend, and a set of policies (glossary, style rule, PII redaction, allowlists) behind a single token.

Anatomy of a route

Every route has the same five-part shape:

Kind. openai, anthropic, mcp, or generic.
Upstream. The base URL of the service you proxy.
Languages. A target language (what the user speaks) and a source language (what the model thinks in).
Translator. passthrough, deepl, or llm.
Policies. Optional glossary, style rule, PII redactor, allowlist, denylist.

The token returned by the admin UI is what callers use as the path segment after the route prefix. For an OpenAI route, the URL looks like /v1/rt_yourtenant_xxxxx/chat/completions.

How tokens are stored

Tokens are hashed with Argon2id before they hit the database. The plain value is shown to you exactly once at creation time. After that, the admin UI only displays the prefix (rt_yourtenant_) and a fingerprint. Lose it, rotate it.

Tokens carry no permission grants of their own. They identify the route. If you need scoped admin access, that lives on the OIDC layer in front of the admin surface, not on route tokens.

Request-time controls

Every header below overrides the route default for one request. All X-AdaptiveApi-* headers are stripped before reaching the upstream, so they never leak into your model context.

Header	Example	Purpose
`X-AdaptiveApi-Target-Lang`	`de`	User language (what the caller speaks).
`X-AdaptiveApi-Source-Lang`	`en`	Upstream working language.
`X-AdaptiveApi-Mode`	`bidirectional`	Direction toggle. Also `request-only`, `response-only`, `off`.
`X-AdaptiveApi-Translator`	`deepl`	Force a translator for this call.
`X-AdaptiveApi-Glossary`	`g_default`	Apply a specific glossary.
`X-AdaptiveApi-Style-Rule`	`s_marketing`	Apply a DeepL v3 style rule.
`X-AdaptiveApi-Model-Type`	`quality_optimized`	DeepL model selector.

Glossaries and style rules

Glossaries are tenant-scoped. Each entry is either a do-not-translate term (kept verbatim) or a source-to-target term map. They map 1:1 to DeepL v3 multilingual glossaries on the wire.

Style rules are DeepL v3 style rules with up to ten 300-character natural-language custom instructions per rule (for example, "always use formal address" or "translate technical terms loosely"). Bind one to a route, override per request with X-AdaptiveApi-Style-Rule.

Allowlists and denylists

Proxy rules constrain which upstream paths a route may hit and which JSON keys are translated. The visual editor under Proxy rules in the admin UI is the easiest path. The underlying shape is:

{
  "allowedPaths": ["/v1/chat/completions", "/v1/responses"],
  "deniedJsonKeys": ["internal_note"],
  "toolArgKeys": ["customer_id"],
  "redactPii": true
}

Auditing

Every request emits an audit row with status, language pair, character counts, duration, integrity-failure flags, and a SHA-256 fingerprint of the Authorization header (never the value). Bodies are off by default. Turn them on per route for debugging, then turn them off again.