# `native` — the provider escape hatch

An alias is a preset plus the keys its admin marked overridable. `native`
is how a caller reaches a provider-native parameter the alias does not
expose, without the gateway pretending to understand it.

    {
      "model": "fast-writer",
      "messages": [ … ],
      "native": { "thinking": { "type": "enabled", "budget_tokens": 2000 } }
    }

Processing order, in the gateway:

1. Your key must carry `allow_native` (off by default). Otherwise
   `403 native_not_permitted`.
2. Any `native` key that the alias preset already sets →
   `400 native_conflicts_with_preset`, naming every colliding key.
3. `native`'s members are merged into the upstream body **last, in the
   provider's vocabulary** — after any dialect translation. The wrapper
   key `native` itself is never sent.
4. A call carrying `native` gets **no fallback**: if the primary target
   fails, the failure is returned rather than a different model run.
5. The budget clamp still applies afterwards and can only lower
   `max_tokens`.

On a concrete model (`openai/gpt-4o-mini`) of the same dialect as your
surface, `native` means the same as top level — every unknown top-level
field is forwarded anyway. It matters on aliases (bypassing the preset)
and on cross-dialect calls (an OpenAI-surface caller reaching an
Anthropic-only field).

## Per-SDK incantation

Typed SDKs strip unknown fields silently. Use each one's escape hatch:

OpenAI Python:

    client.chat.completions.create(model="fast-writer", messages=[...],
        extra_body={"native": {"thinking": {"type": "enabled", "budget_tokens": 2000}}})

Anthropic Python:

    client.messages.create(model="fast-writer", max_tokens=1024, messages=[...],
        extra_body={"native": {"top_k": 40}})

OpenAI Node:

    await client.chat.completions.create({
      model: "fast-writer", messages: [...],
      native: { thinking: { type: "enabled", budget_tokens: 2000 } },
    } as any);

openai-go:

    client.Chat.Completions.New(ctx, params,
        option.WithJSONSet("native", map[string]any{"thinking": map[string]any{"type": "enabled", "budget_tokens": 2000}}))

curl: put `native` in the JSON body.

## What you cannot do with it

`native` cannot override a preset key, cannot change `model`, and is not
validated against a schema unless the admin fetched one for the target
model — in which case unknown or ill-typed keys are `400 native_invalid`,
naming them. With no schema cached the gateway forwards blind and the
provider decides; it never rejects for want of a schema.