Model aliases

List and retrieve rich alias releases, and install a new immutable release as an admin. Aliases resolve to immutable releases so routing stays reproducible.

A model alias points at exactly one immutable release. Every request records which release it resolved through, so routing decisions are reproducible and a frozen alias never drifts. Unlike /v1/models, this surface exposes the full release: every target, its execution profile, and the capability-manifest revision it was pinned against. Release ids are prefixed alr_. See model aliases.

All requests require a bearer API key. Listing and retrieving need any valid key; installing a release needs the admin scope. See authentication.

List aliases

GET /v2/model-aliases

Returns every live alias release, sorted by alias name.

curl https://api.zumik.ai/v2/model-aliases \
  -H "Authorization: Bearer $ZUMIK_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "alr_01jy7nhi23m5n6o7p8q9r0s1tu",
      "object": "model_alias_release",
      "alias": "code.fast",
      "status": "active",
      "policy_revision": "policy_7",
      "capability_manifest_revision": "cap_2026_06_09",
      "targets": [
        {
          "execution_profile": "managed_provider",
          "provider": "openai",
          "model": "gpt-4o",
          "model_revision": "2025-01-01",
          "weight": 60
        },
        {
          "execution_profile": "managed_provider",
          "provider": "fireworks_ai",
          "model": "llama-v4-maverick",
          "model_revision": "2025-06-01",
          "weight": 40
        }
      ]
    }
  ]
}

objectstring

Always list.

dataarray

The alias releases.

Retrieve an alias

GET /v2/model-aliases/{alias}

aliasstringpathrequired

The alias name, e.g. code.fast.

curl https://api.zumik.ai/v2/model-aliases/code.fast \
  -H "Authorization: Bearer $ZUMIK_API_KEY"

Returns the alias release object.

idstring

Opaque release id, prefixed alr_.

objectstring

Always model_alias_release.

aliasstring

The alias name.

statusstring

active or retired.

policy_revisionstring

The routing-policy revision this release was pinned against.

capability_manifest_revisionstring

The capability-manifest revision the targets were validated against.

targetsarray

The weighted resolution targets. Each has execution_profile (managed_provider, byok, byoc_dynamo, byoc_epp, or subscription), provider, model, model_revision, and weight.

Install a release

PUT /v2/model-aliases/{alias}

Installs a new immutable release for an alias. Every call mints a fresh release id; changing a target is a new release, never an in-place edit. Resolution picks up the new release on the next request. Requires the admin scope.

aliasstringpathrequired

The alias name to install a release for.

targetsarrayrequired

At least one target. Weights must sum to a positive value, and each target needs a non-empty provider and model.

target

execution_profilestringrequired

One of managed_provider, byok, byoc_dynamo, byoc_epp, subscription.

providerstringrequired

The provider, e.g. openai.

modelstringrequired

The model id at the provider.

model_revisionstringrequired

The pinned model revision.

weightintegerrequired

The resolution weight for this target.

policy_revisionstringdefault: policy_custom

The routing-policy revision to record.

capability_manifest_revisionstringdefault: cap_custom

The capability-manifest revision to record.

curl -X PUT https://api.zumik.ai/v2/model-aliases/code.fast \
  -H "Authorization: Bearer $ZUMIK_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "targets": [
      { "execution_profile": "managed_provider", "provider": "openai", "model": "gpt-4o", "model_revision": "2025-01-01", "weight": 100 }
    ]
  }'

Returns the newly installed release object.

Errors

Status	Code	When
400	`invalid_request_error`	Empty alias name, no targets, weights summing to zero, or a target missing `provider`/`model`.
401	`invalid_api_key`	Missing or invalid API key.
403	`insufficient_scope`	The key lacks the `admin` scope required to install a release.
404	`invalid_request_error`	The alias does not exist (on retrieve).

See the full table on errors.

Model aliases

List aliases

Retrieve an alias

Install a release

Errors

On this page