> Raw Markdown twin (generated at build time from the source Markdown). Rendered page: https://docs.gatellm.io/en/reference/field-reference · Doc index: https://docs.gatellm.io/en/llms.txt


# Field reference index

When filling console forms or submitting config via the Console API, if you're unsure what a field is or which entity it belongs to, check this quick-reference table first to locate it; for full semantics, defaults, and examples, go to each section's linked detail page. Covers seven entity types: upstreams, models, load balancers, access keys, key groups, MCP servers, and access rules.

## Upstream

See [Upstream and model fields](/en/reference/upstreams-models-fields.md).

| Field | Type | Description |
|------|------|------|
| `name` | string | Unique name, referenced by models |
| `protocol` | enum | See the [Protocol interop matrix](/en/reference/protocol-matrix.md) protocol list |
| `base_url` | string | Upstream address, no trailing `/` |
| `api_keys` | array | Multi-key deterministic weighted distribution (same caller sticks to the same key), each item has `key` + `weight` (0=standby); algorithm in [Upstream and model fields → Multi-key and weights](/en/reference/upstreams-models-fields.md#multi-key-weights) |
| `user_agent` | string? | Overrides the global UA, supports `{{...}}` template variables |
| `headers` | map | Custom headers, supports `{{var}}` and `{{alt1\|alt2}}` fallback chains; available variables in [Template variable reference](/en/reference/template-variables.md) |
| `proxy` | string? | Outbound proxy |
| `dns_servers` | array | per-upstream DNS (≤8), DoH/DoT/UDP auto-detected |
| `dns_ttl_secs` | u64 | DNS cache TTL, default 30 |
| `request_payload` | array | Request-body rewrite rules (path/value/mode; value supports `{{...}}` expressions for dynamic values, available variables in [Template variable reference](/en/reference/template-variables.md)). Rewrite-type rules apply against the target shape after protocol translation; `switch-route` is the exception — it doesn't change the body, and evaluates `when` against the **client** shape before translation (an OR-semantics predicate list, each `{path, eq?}`: omitting `eq`=existence, giving `eq`=equality, `*` wildcards take existence semantics), triggering an immediate switch when hit, `use_model` being the switch target (supports cross-protocol) |
| `request_transform_before` | script? | Pre-translation request-phase JS (see [Scripting API reference](/en/reference/scripting-api.md)) |
| `request_transform_after` | script? | Post-translation request-phase JS (see [Scripting API reference](/en/reference/scripting-api.md)) |
| `response_transform` | script? | Response-phase JS (not supported for streaming) |
| `script_error_mode` | enum | `log-and-continue` / `log-and-reject` |
| `count_token` | enum | `upstreamApi` / `tiktoken` |
| `rate_limit` | object? | Upstream-level rate limit (`rpm` / `max_concurrency` / `tpm` / `tps_min_interval_ms` / `wait_timeout_secs` / `initial_tokens`), fields in [Upstream and model fields](/en/reference/upstreams-models-fields.md) |
| `enabled` | bool | default true |
| `extra_config` | json? | vendor extension |

## Model

See [Upstream and model fields](/en/reference/upstreams-models-fields.md).

| Field | Type | Description |
|------|------|------|
| `name` | string | The public model name, clients call this |
| `upstream` | string | The owning upstream |
| `upstream_model_id` | string | The real model name sent to the upstream |
| `aliases` | array | Extra usable names (share a globally unique space with the primary name) |
| `hide_name` | bool | true means the primary name is inaccessible (404), only alias/LB access |
| `protocol` | enum? | Overrides the upstream protocol |
| `base_url` | string? | Overrides the upstream base_url; treated as a full endpoint URL with `direct_path` |
| `kind` | string? | Variant identifier for DashScope etc. |
| `inference_profile` | string? | Bedrock inference config |
| `request_payload` | array? | Request-body rewrite rules (overrides upstream-level; value supports `{{...}}` expressions for dynamic values, variable scope in [Template variable reference](/en/reference/template-variables.md)). The `switch-route` mode uses `when` + `use_model`, see the upstream row |
| `request_transform_before` | script? | Model-level pre-translation request script (overrides upstream-level) |
| `request_transform_after` | script? | Model-level post-translation request script (overrides upstream-level) |
| `response_transform` | script? | Model-level response script |
| `script_error_mode` | enum? | override |
| `rate_limit` | object? | `inherit` or concrete values |
| `count_token` | enum? | override |
| `enabled` | bool | |

## Load balancer

See [Load-balancing fields](/en/reference/load-balancing-fields.md).

| Field | Type | Description |
|------|------|------|
| `name` | string | The model name clients fill in |
| `aliases` | array | Extra usable names |
| `entries` | array | Entries, each `{upstream, model, weight}` (0–255, 0=standby) |
| `retry_on_different_node` | bool | default true, switch nodes on error |
| `extra_config.sticky_session_enabled` | bool | Sticky sessions (nested under `extra_config`, default `true`; not a top-level field) |
| `binding_ttl_secs` | u64 | Sticky TTL, default 300; 0=permanent |
| `binding_key_template` | string | Binding-key template, `{{...}}` expression; available variables in [Template variable reference](/en/reference/template-variables.md) |
| `static_bindings` | array | Admin static bindings (binding_key + upstream + model + access_key name/group) |
| `enabled` | bool | default true |

## Access key (AccessKey)

See [Access key and key group fields](/en/reference/access-keys-groups-fields.md).

| Field | Type | Description |
|------|------|------|
| `name` | string | Identifier, read-only on edit |
| `api_key` | string | The credential the client presents; list shows a mask, full value fetched on demand |
| `group` | string? | The owning key group, determines model/MCP permission |
| `model_mappings` | array | `from → to` model rewrites specific to this key (can carry `when` header conditions); higher priority than the owning group's rules; empty=no mapping. See [Configure identity model mapping](/en/howto/configure-identity-model-mapping.md) |
| `anonymous` | bool | Anonymous fallback (globally unique) |
| `enabled` | bool | Unchecking revokes it |
| `acl_default_action` | enum? | `allow` / `deny`, per-key fallback action when no rule matches |
| `created_by` | string? | The creating console username |

## Key group (AccessKeyGroup)

See [Access key and key group fields](/en/reference/access-keys-groups-fields.md).

| Field | Type | Description |
|------|------|------|
| `name` | string | Group identifier |
| `models` | array | Accessible models; empty=no permission, `["*"]`=all |
| `load_balancers` | array | Accessible load balancers |
| `model_mappings` | array | `from → to` model rewrites shared by this group (can carry `when` header conditions), applied to all keys in the group; lower priority than the key's own rules, higher than passthrough. See [Configure identity model mapping](/en/howto/configure-identity-model-mapping.md) |
| `mcp_tool_acl` | object | `{allowed_tools, denied_tools, allowed_tags}`, see [MCP configuration](/en/reference/mcp-config.md) |
| `acl_default_action` | enum? | `allow` / `deny`, per-group fallback action when no rule matches |

## MCP server (McpServer)

See [MCP configuration](/en/reference/mcp-config.md).

| Field | Type | Description |
|------|------|------|
| `name` | string | Unique, used as the tool prefix |
| `transport` | enum | `streamable_http` / `sse` |
| `connection_type` | enum | `stateful` / `stateless` / `rest_bridge` |
| `endpoint` | string | Upstream URL |
| `auth_header` | string? | Upstream Authorization header |
| `extra_headers` | map? | Extra headers |
| `tags` | array | Coarse-grained ACL tags |
| `priority` | i32 | 0–999, smaller = higher priority |
| `idle_timeout_secs` | u32 | default 300 |
| `defer_loading` | bool | load only on first call |
| `health_check` | object? | path / interval(60s) / timeout(5s) |
| `max_concurrency` | u32? | per-access-key concurrency cap |
| `rate_limit` | object? | rps / tpm |
| `extra_config` | json? | REST bridge needs the simplified REST spec JSON (`{title, version, operations[]}`) |
| `enabled` | bool | |

## Access rule (AclRule)

See [Header ACL rule fields](/en/reference/header-acl-rules.md).

| Field | Type | Description |
|------|------|------|
| `name` | string | Globally unique identifier, immutable after creation |
| `rule_type` | string | currently only `header` |
| `condition_key` | string | HTTP request header name; empty when `condition_type = any` |
| `condition_type` | enum | `exact` / `prefix` / `regex` / `exists` / `absent` / `any`. `any` means the condition is always true and no header is inspected, the rule acting purely by scope (then `condition_key` is empty). `regex` defaults to unanchored "contains" semantics; full match needs `^...$`, multi-condition uses `\|`, see the "regex matching semantics" section of [Header ACL rule fields](/en/reference/header-acl-rules.md) |
| `condition_value` | string? | Match value; must be empty for `exists`/`absent`/`any` |
| `action` | enum | `allow` / `deny` |
| `enabled` | bool | Rule switch; disabled rules are ignored at load time |
| `sort_order` | int | Ascending priority, smaller = evaluated first; same value evaluated by scope global → group → key |
| `scope_key` | string[] | Restrict to one or more access keys, mutually exclusive with `scope_group`; empty array=global |
| `scope_group` | string[] | Restrict to one or more key groups, mutually exclusive with `scope_key`; empty array=global |

## Related sections

- Upstream/model field details: [Upstream and model fields](/en/reference/upstreams-models-fields.md)
- Load-balancer field details: [Load-balancing fields](/en/reference/load-balancing-fields.md)
- Access key and key group field details: [Access key and key group fields](/en/reference/access-keys-groups-fields.md)
- Header ACL rule field details: [Header ACL rule fields](/en/reference/header-acl-rules.md)
- MCP server field details: [MCP configuration](/en/reference/mcp-config.md)
- Template variable list: [Template variable reference](/en/reference/template-variables.md)
- Protocol list: [Protocol interop matrix](/en/reference/protocol-matrix.md)
- Error code list: [Error code reference](/en/reference/error-codes.md)