---
title: Model versioning
description: How models are versioned, evaluated, and promoted, with aliases you control from the dashboard.
---

Every model available to your organization — an RFM model for one of your targets, a GFM model, or a downstream model trained on GFM embeddings — has its own version history. You decide which version serves your traffic.

The workflow has two halves. Avra releases each new version as a governed release, evaluated before it's offered to you. Then you decide what to do with it: run it beside the version in production, point the `production` alias at it when it has earned that, and point the alias back if something regresses. Your code doesn't change at any step, because it calls the alias.

<svg class="fig" viewBox="0 0 640 248" role="img" aria-label="Three panels. Today: production points at version 3 and challenger points at version 4. Promote: challenger is removed and production points at version 4. Roll back: production points at version 3 again.">
  <defs>
    <marker id="fig-alias-arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
      <path d="M0,0 L10,5 L0,10 z" class="arrow" />
    </marker>
    <marker id="fig-alias-arrow-accent" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
      <path d="M0,0 L10,5 L0,10 z" class="arrow-accent" />
    </marker>
  </defs>
  <rect class="card" x="4" y="8" width="200" height="232" rx="8" />
  <text class="title" x="18" y="32">1. Today</text>
  <rect class="card" x="116" y="52" width="76" height="30" rx="6" />
  <text class="mono mid" x="154" y="71">version 2</text>
  <rect class="card" x="116" y="100" width="76" height="30" rx="6" />
  <text class="mono mid" x="154" y="119">version 3</text>
  <rect class="card" x="116" y="148" width="76" height="30" rx="6" />
  <text class="mono mid" x="154" y="167">version 4</text>
  <rect class="solid" x="14" y="102" width="82" height="26" rx="13" />
  <text class="small mid on-solid" x="55" y="119">production</text>
  <line class="edge-accent" x1="96" y1="115" x2="114" y2="115" marker-end="url(#fig-alias-arrow-accent)" />
  <rect class="soft" x="14" y="150" width="82" height="26" rx="13" />
  <text class="small mid" x="55" y="167">challenger</text>
  <line class="edge" x1="96" y1="163" x2="114" y2="163" marker-end="url(#fig-alias-arrow)" />
  <text class="small label mid" x="104" y="208">production serves</text>
  <text class="small label mid" x="104" y="224">version 3</text>
  <rect class="card" x="216" y="8" width="200" height="232" rx="8" />
  <text class="title" x="230" y="32">2. Promote</text>
  <rect class="card" x="328" y="52" width="76" height="30" rx="6" />
  <text class="mono mid" x="366" y="71">version 2</text>
  <rect class="card" x="328" y="100" width="76" height="30" rx="6" />
  <text class="mono mid" x="366" y="119">version 3</text>
  <rect class="card" x="328" y="148" width="76" height="30" rx="6" />
  <text class="mono mid" x="366" y="167">version 4</text>
  <rect class="solid" x="226" y="150" width="82" height="26" rx="13" />
  <text class="small mid on-solid" x="267" y="167">production</text>
  <line class="edge-accent" x1="308" y1="163" x2="326" y2="163" marker-end="url(#fig-alias-arrow-accent)" />
  <text class="small label mid" x="316" y="208">remove challenger, then</text>
  <text class="small label mid" x="316" y="224">reassign production</text>
  <rect class="card" x="428" y="8" width="200" height="232" rx="8" />
  <text class="title" x="442" y="32">3. Roll back</text>
  <rect class="card" x="540" y="52" width="76" height="30" rx="6" />
  <text class="mono mid" x="578" y="71">version 2</text>
  <rect class="card" x="540" y="100" width="76" height="30" rx="6" />
  <text class="mono mid" x="578" y="119">version 3</text>
  <rect class="card" x="540" y="148" width="76" height="30" rx="6" />
  <text class="mono mid" x="578" y="167">version 4</text>
  <rect class="solid" x="438" y="102" width="82" height="26" rx="13" />
  <text class="small mid on-solid" x="479" y="119">production</text>
  <line class="edge-accent" x1="520" y1="115" x2="538" y2="115" marker-end="url(#fig-alias-arrow-accent)" />
  <text class="small label mid" x="528" y="208">reassign production</text>
  <text class="small label mid" x="528" y="224">back to version 3</text>
</svg>

An alias moves; the versions stay. Promoting reassigns `production` to another version, and rolling back reassigns it again. A version holds at most one alias, so `challenger` comes off version 4 first.

## Models and versions

Each model is identified by a **`model_id`**. Each version has a unique, immutable **`version_id`**, and only **active** versions can serve predictions. Several versions of a model can be active at once, so you can run a challenger beside the version serving production or test a new version without disrupting production. You can also serve different versions to different segments or workflows, and roll back at once when something regresses.

`GET /v1/api/models/{model_id}/versions` lists a model's versions. Each one has its `model_version_id`, a `version` number, `is_active`, the date it was trained as `trained_at`, and its `alias` when it holds one.

## Aliases

An **alias** is a name that points at one version of a model, such as `production` or `challenger`. Calls that use an alias go to whichever version holds it.

You choose the names. Common ones are `production`, `challenger`, and `baseline`, but none is built in. An alias points at a single version, and a version carries at most one alias. A model's aliases apply to every workspace in your organization.

Alias names are lowercase. Avra turns spaces and underscores into hyphens, removes accents, and drops any other character that isn't a letter, a digit, or a hyphen, so `Champion 2` becomes `champion-2`. In the path of a call, Avra reads a UUID as a version ID and anything else as an alias.

## The life of a version

A version is either active or inactive, and it can hold an alias in either state. Only an active version serves live calls. You assign and remove aliases from the dashboard.

| State | Calls by `version_id` | Calls by alias |
|---|---|---|
| **Active** | Served | No alias to call |
| **Active, holds an alias** | Served | Served |
| **Inactive** | `400 model version is not active` | No alias to call |
| **Inactive, holds an alias** | `400 model version is not active` | `400 model version is not active` |

An **archived** version is retired: it's inactive and takes no new batches. When a model is archived, so are its versions.

An alias doesn't move when its version becomes inactive. Calls through that alias fail until you reassign it to an active version.

## Pin a version or follow an alias

Follow an alias, such as `production`, to pick up promotions without changing code: `POST /v1/api/prediction/{model_id}/production` calls whichever version holds it. **Pin an exact version** when you need determinism, such as for backtests, audit replays, or staged rollouts: `POST /v1/api/prediction/{model_id}/{version_id}` always reaches the same immutable version.

The prediction response doesn't name the version that answered. To know exactly which version produced each result, read the version an alias points at, store its `model_version_id`, and call that ID:

```bash cURL
MODEL_ID="<model_id>"

# Follow the alias: reaches whichever version holds production at the time.
curl -X POST "https://api.avra.ai/v1/api/prediction/$MODEL_ID/production" \
  -H "Authorization: Bearer $AVRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cnpj": "12345678000199"}'

# Pin: resolve the alias once, then call the exact version.
VERSION_ID=$(curl -s "https://api.avra.ai/v1/api/models/$MODEL_ID/versions/production" \
  -H "Authorization: Bearer $AVRA_API_KEY" | jq -r '.model_version_id')

curl -X POST "https://api.avra.ai/v1/api/prediction/$MODEL_ID/$VERSION_ID" \
  -H "Authorization: Bearer $AVRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cnpj": "12345678000199"}'
```

```python Python
import os

import requests

API = "https://api.avra.ai"
MODEL_ID = "<model_id>"
headers = {"Authorization": f"Bearer {os.environ['AVRA_API_KEY']}"}
inputs = {"cnpj": "12345678000199"}

# Follow the alias: reaches whichever version holds production at the time.
following = requests.post(
    f"{API}/v1/api/prediction/{MODEL_ID}/production", headers=headers, json=inputs, timeout=35
)
following.raise_for_status()

# Pin: resolve the alias once, store the version ID, then call it.
version = requests.get(
    f"{API}/v1/api/models/{MODEL_ID}/versions/production", headers=headers, timeout=30
)
version.raise_for_status()
version_id = version.json()["model_version_id"]

pinned = requests.post(
    f"{API}/v1/api/prediction/{MODEL_ID}/{version_id}", headers=headers, json=inputs, timeout=35
)
pinned.raise_for_status()
print(version_id, pinned.json()["result"])
```

```ts TypeScript
const API = "https://api.avra.ai";
const MODEL_ID = "<model_id>";
const headers = {
  Authorization: `Bearer ${process.env.AVRA_API_KEY}`,
  "Content-Type": "application/json",
};
const body = JSON.stringify({ cnpj: "12345678000199" });

// Follow the alias: reaches whichever version holds production at the time.
const following = await fetch(`${API}/v1/api/prediction/${MODEL_ID}/production`, {
  method: "POST",
  headers,
  body,
});
if (!following.ok) throw new Error(`${following.status} ${await following.text()}`);

// Pin: resolve the alias once, store the version ID, then call it.
const version = await fetch(`${API}/v1/api/models/${MODEL_ID}/versions/production`, { headers });
if (!version.ok) throw new Error(`${version.status} ${await version.text()}`);
const { model_version_id: versionId } = await version.json();

const pinned = await fetch(`${API}/v1/api/prediction/${MODEL_ID}/${versionId}`, {
  method: "POST",
  headers,
  body,
});
if (!pinned.ok) throw new Error(`${pinned.status} ${await pinned.text()}`);
console.log(versionId, (await pinned.json()).result);
```

Batches take the same choice. Send `alias` or `model_version_id` to `POST /v2/api/batches`. If you send both, they must point at the same version, or the request fails with `409`. A batch keeps the version it resolved when you created it, so moving an alias doesn't change a batch that's already running. See [Batch inference](/core/batch-inference).

## Promote and roll back

Aliases are managed in the dashboard. Open a model under **Models** to see its versions and which ones are active, and reassign an alias, such as `production`, to another active version. Managing aliases needs the matching permission. See [Roles & permissions](/dashboard/roles-permissions). A reassignment takes effect on the next call, with no code change or deployment on your side.

1. **Check that the new version is active**

    On the model's page, an active version shows **Live & Batch**. Calls by its `version_id` reach it, while the alias still points at the version in production.

2. **Free it from any other alias**

    A version carries at most one alias. If the new version holds one, such as `challenger`, remove that alias first.

3. **Reassign production**

    In the version's **⋯** menu, select **Manage aliases** and enter `production`. The alias is already in use, so turn on **Reassign existing alias** and save. The next call to `production` reaches the new version.

4. **Watch the new version**

    While the previous version is active, a rollback is one reassignment away.

**Roll back** by reassigning the alias to the previous version, the same way. This works while the previous version is active, because an alias on an inactive version can't serve calls.

## Events

Version changes send `model-version-*` events to your [webhooks](/core/webhooks):

| Event | Sent when |
|---|---|
| `model-version-promotion` | An alias is assigned to a version, including a reassignment |
| `model-version-demotion` | An alias is removed from a version |
| `model-version-activation` | A version is activated |
| `model-version-deactivation` | A version is deactivated |

A reassignment sends one `model-version-promotion`, for the version that receives the alias, and no demotion for the version that loses it. Subscribe to `model-version-promotion` to know when to refresh what you store, such as embeddings.

## Every version is governed

A version reaches your organization only as a governed release: authorized by Avra's research team and approved by someone who didn't train it.

```mermaid
flowchart TB
  release["Governed release<br/>authorized and approved"] --> offer["Offered for<br/>promotion"]
  offer --> you["You decide"]
  class you accent
  classDef accent fill:#0A01FE,stroke:#0A01FE,color:#fff
```

You choose when, and whether, to promote it. See [Evaluation](/rfm/evaluation).

## When versions change what you store

Embeddings and scores from different versions aren't interchangeable. When you move to a new version of an embedding model, embed again and retrain the models built on those embeddings. When you move to a new version of a scoring model, revalidate the thresholds and risk bands that depend on it. See the [embeddings technical guide](/gfm/embeddings/technical-implementation#versions-and-caching).

## Where to go next

**[Live predictions](/core/predictions)**

Call a version by alias or by ID.

**[Webhooks](/core/webhooks)**

Receive `model-version-*` events.

**[Evaluation](/rfm/evaluation)**

How a version is measured before you promote it.

**[Roles & permissions](/dashboard/roles-permissions)**

Who can move aliases.
