# Model aliases (/api-v2/model-aliases)



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](/concepts/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](/api-reference/authentication).

## List aliases [#list-aliases]

`GET /v2/model-aliases`

Returns every live alias release, sorted by alias name.

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

```json
{
  "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
        }
      ]
    }
  ]
}
```

<ResponseField name="object" type="string">
  Always `list`.
</ResponseField>

<ResponseField name="data" type="array">
  The alias releases.
</ResponseField>

## Retrieve an alias [#retrieve-an-alias]

`GET /v2/model-aliases/{alias}`

<ParamField path="alias" type="string">
  The alias name, e.g. `code.fast`.
</ParamField>

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

Returns the alias release object.

<ResponseField name="id" type="string">
  Opaque release id, prefixed `alr_`.
</ResponseField>

<ResponseField name="object" type="string">
  Always `model_alias_release`.
</ResponseField>

<ResponseField name="alias" type="string">
  The alias name.
</ResponseField>

<ResponseField name="status" type="string">
  `active` or `retired`.
</ResponseField>

<ResponseField name="policy_revision" type="string">
  The routing-policy revision this release was pinned against.
</ResponseField>

<ResponseField name="capability_manifest_revision" type="string">
  The capability-manifest revision the targets were validated against.
</ResponseField>

<ResponseField name="targets" type="array">
  The weighted resolution targets. Each has `execution_profile` (`managed_provider`, `byok`, `byoc_dynamo`, `byoc_epp`, or `subscription`), `provider`, `model`, `model_revision`, and `weight`.
</ResponseField>

## Install a release [#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.

<ParamField path="alias" type="string">
  The alias name to install a release for.
</ParamField>

<ParamField body="targets" type="array">
  At least one target. Weights must sum to a positive value, and each target needs a non-empty `provider` and `model`.

  <Expandable title="target">
    <ParamField body="execution_profile" type="string">
      One of `managed_provider`, `byok`, `byoc_dynamo`, `byoc_epp`, `subscription`.
    </ParamField>

    <ParamField body="provider" type="string">
      The provider, e.g. `openai`.
    </ParamField>

    <ParamField body="model" type="string">
      The model id at the provider.
    </ParamField>

    <ParamField body="model_revision" type="string">
      The pinned model revision.
    </ParamField>

    <ParamField body="weight" type="integer">
      The resolution weight for this target.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="policy_revision" type="string" default="policy_custom">
  The routing-policy revision to record.
</ParamField>

<ParamField body="capability_manifest_revision" type="string" default="cap_custom">
  The capability-manifest revision to record.
</ParamField>

```bash
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 [#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](/api-reference/errors).