---
title: "Update an alias's metadata"
method: PATCH
path: "/v2/agent_aliases/{alias_key}"
tags: ["Agent Aliases"]
---

# Update an alias's metadata

`PATCH /v2/agent_aliases/{alias_key}`

Updates an alias's metadata fields (name, description, enabled, metadata). To replace the routing policy, use `PUT /v2/agent_aliases/{alias_key}/policy`. Policies are atomic and do not support partial updates.

## Path parameters

- `alias_key` string, required — The unique key that identifies an alias. Alias keys are independent of agent keys. The same string can exist as both an alias key and an agent key in the same customer account. Calls to `/v2/agent_aliases/{key}/...` target the alias. Calls to `/v2/agents/{key}/...` target the agent.

## Headers

- `Request-Timeout` integer
- `Request-Timeout-Millis` integer

## Request body

- UpdateAgentAliasRequest — Request body for updating an alias's metadata fields. Use `PUT /v2/agent_aliases/{alias_key}/policy` to replace the routing policy itself. Policies are atomic and do not support partial updates.
  - `name` string
  - `description` string
  - `enabled` boolean
  - `metadata` object

## Response `200`

The updated alias.

- AgentAlias — A routing primitive that maps a public name to one or more agents under a configurable policy. When a session is created through an alias (via `POST /v2/agent_aliases/{alias_key}/sessions`), the alias's policy selects the underlying agent that runs the session. Use aliases for: - Canary rollouts — weighted routing between two agents. - Tenant routing — different agents for different customers, based on your tenant metadata. - A stable handle in front of agents whose configuration evolves. The resolved agent's session_enrichment applies to sessions created through the alias, after routing resolves. Routing runs before enrichment. Routing rules therefore read the request metadata, not enriched values. Routing rules use userfn expressions. See the `AliasRule.match` field for the context shape and example expressions.
  - `key` string, required — The unique key that identifies an alias. Alias keys are independent of agent keys. The same string can exist as both an alias key and an agent key in the same customer account. Calls to `/v2/agent_aliases/{key}/...` target the alias. Calls to `/v2/agents/{key}/...` target the agent.
  - `name` string, required — A human-readable name for the alias.
  - `description` string, nullable — A longer description of what this alias represents.
  - `policy` AliasPolicy, required — Evaluates ordered rules against the session context. The policy selects the first rule whose `match` expression evaluates to true. The selected rule's `targets` shape determines what runs. `single` routes directly to one agent. `weighted` picks one of several agents by hashing the rule's `partition_by` expression. A rule with no `match` always matches (catch-all). It must be the last rule. The platform rejects any rule placed after a catch-all as unreachable. This single shape covers: - Direct routing — one rule, single target. - Weighted or canary rollouts — one rule, weighted targets. - Conditional routing — multiple rules with matches. - Conditional plus canary — multiple rules, each independently single or weighted.
    - `type` string, required
    - `rules` AliasRule[], required — Ordered routing rules. The policy evaluates rules top-to-bottom and selects the first rule whose `match` expression evaluates to true. Include at least one rule with no `match` (a catch-all) to guarantee a fallback target.
      - `match` string — UserFn expression evaluating to boolean. Uses the `get()` function with JSONPath to access the context. See https://docs.vectara.com/docs/search-and-retrieval/rerankers/user-defined-function-reranker for the UserFn language reference. Omit for a catch-all rule. Missing paths return `null`. Comparing against `null` is falsy, so the rule falls through to the next one in the policy. Use `get('$.path', default)` for an explicit fallback. Context shape — at resolution time the underlying agent is not yet selected. The `agent.*` fields therefore reflect the *alias's* metadata (name, description, metadata), with the alias's URL key in `agent.key`. Use these for alias-level context (e.g. `$.agent.metadata.region`). Use `session.*` for per-call routing inputs (tenant, user_id, etc.). Most rules dispatch on `session.*`. ``` { "agent": { "name", "key", "description", "metadata": { ... } }, // alias's metadata at resolution time "session": { "key", "name", "description", "metadata": { ... } }, // the session being created "currentDate": "2026-01-15T10:35:00Z" } ``` Examples: * `get('$.session.metadata.tenant') == 'us'` * `(get('$.session.metadata.tenant') == 'us') and (get('$.session.metadata.tier') == 'gold')` * `(get('$.session.metadata.region') == 'us-west') or (get('$.session.metadata.region') == 'us-east')` * `get('$.session.metadata.tier', 'free') != 'free'`
      - `targets` union, required — The shape of a rule's targets. The `type` discriminator selects which fields apply: * `single` — a direct route to one agent. No weight, no partition function. * `weighted` — a weighted selection among several agents. Requires a `partition_by` userfn expression that names what to hash on. Different rules can use different partition functions.
        - SingleRuleTargets — Direct route to a single agent. The `agent_key` must reference an existing agent owned by the same customer.
          - `type` string, required
          - `agent_key` string, required — The key of the underlying agent this rule routes to.
        - WeightedRuleTargets — Weighted selection among several agents. The policy evaluates and hashes the `partition_by` userfn expression. The result picks which `options` entry serves the session. Different rules in the same policy can declare different `partition_by` expressions (US rules canary by user_id, EU rules by tenant_id, etc.).
          - `type` string, required
          - `partition_by` string, required — UserFn expression whose result is stringified and hashed to pick among `options`. Required: no implicit default. Uses the `get()` function with JSONPath to access the context. See https://docs.vectara.com/docs/search-and-retrieval/rerankers/user-defined-function-reranker for the UserFn language reference. Use `get('$.session.key')` for per-session canary, `get('$.session.metadata.user_id', '')` for per-user canary. If the expression evaluates to `null` at resolution time, the request fails with a 400. Wrap optional fields with a default via `get('$.path', '')`.
          - `options` WeightedTarget[], required — Weighted target options. The hash of the `partition_by` result selects one option. Weights are normalized at evaluation time.
            - `agent_key` string, required — The key of the underlying agent this option routes to.
            - `weight` integer, required — Weight used when selecting among the weighted options. Absolute non-negative integer, normalized at evaluation time.
  - `enabled` boolean, required — Whether this alias is currently invocable.
  - `metadata` object, nullable — Arbitrary metadata associated with the alias.
  - `created_at` string, date-time, required — Timestamp when the alias was created.
  - `updated_at` string, date-time, nullable — Timestamp when the alias was last updated.

## Other responses

- `403` — Permissions do not allow modifying this alias.
- `404` — Alias not found.

---

[API](https://skmtc.net/vectara/apis/vectara-rest-api-v2.md) · [All operations](https://skmtc.net/vectara/apis/vectara-rest-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/vectara/vectara-rest-api-v2/versions/e85040b266cc/schema)