# Models and versions

> The model alias, exact versions and what they freeze, the fallback versions, the version lifecycle and the models endpoint.

You choose a model with the `model` field of a request. It takes an alias, which moves to newer versions over time, or an exact version, which never changes. Every response names the exact version that answered.

## Alias and exact version

| Form | Example | What it does |
| --- | --- | --- |
| Alias | `dex-1` | Resolves to the newest active exact version in major version 1. It moves when a new version ships, and the [changelog](/docs/changelog/) records each move. This is the default when you leave `model` out. |
| Exact version | `dex-1.0.0` | A frozen serving profile, named `dex-MAJOR.MINOR.PATCH`. The same request to it always gives the same answers. |

The `model` field of every response is the exact version that answered, even when you sent the alias. A name that does not exist gives `404 model_not_found`. A version that has been retired gives `404 model_retired`.

## What an exact version freezes

An exact version fixes everything that could change an answer:

- the model weights, the tokenizer and the quantization recipe;
- the prompt template and the codes used to read answers;
- the inference software build with its pinned dependencies, and the hardware configuration;
- the [calibration](/docs/concepts/calibration/) version;
- a golden hash: a fingerprint of the engine's raw outputs on a fixed suite of 500 requests.

A change to any of these ships as a new version. A new calibration alone is a new PATCH version. A new tokenizer is a new major version, so every version in major version 1 counts tokens the same way.

## Versions

| Version | Released | What changed |
| --- | --- | --- |
| `dex-1.0.0` | 25 September 2026 | The first version, calibration `cal-20260925-1`. |
| `dex-1.0.1` | 26 September 2026 | The alias `dex-1` points here. Your text can no longer act as prompt structure: a `</state>` inside the state, or markup such as `<think>` and `<tool_call>` anywhere in a request, is read as plain text. Same model and engine as `dex-1.0.0`; calibration `cal-20260926-1`. |

Requests without such text get the same decisions on both versions in nearly every case; the probabilities differ slightly, because `dex-1.0.1` reads one more line after the state and has its own calibration. See the [changelog](/docs/changelog/) and the [calibration reports](/docs/calibration/).

## Fallback versions

When the GPU path cannot answer an alias request, a hosted fallback may answer instead. It has versions of its own:

| Version | Upstream model |
| --- | --- |
| `dex-fallback-1.0.0` | Azure OpenAI gpt-4.1-mini (2025-04-14), Data Zone Standard, EU |
| `dex-fallback-lite-1.0.0` | Azure OpenAI gpt-4o-mini (2024-07-18), Data Zone Standard, EU |

Each is calibrated separately and is not deterministic. You cannot request a fallback version directly; Dex chooses between them. Both upstream models retire on 14 April 2027, which `GET /v1/models` shows as their `retires_at`. See [Fallback and served_by](/docs/concepts/fallback/).

## Lifecycle

A version's `status` is `active`, `deprecated` or `retired`.

- When a new version becomes the alias target, the version it replaces stays available for at least 90 days.
- `GET /v1/models` shows each version's `retires_at`.
- Account owners get an email 30 days and 7 days before a version retires.
- After that, a request that names it gets `404 model_retired`.

Within v1, the API changes only by adding things: new optional request fields, new response fields and new error codes. Write your code to ignore response fields it does not know.

## Which one to use

- **Use the alias** to get improvements without changing code. Expect answers to change when the alias moves, and watch the changelog.
- **Pin an exact version** when answers must not change, for example for snapshot tests, audits or regulated workflows. Plan the move to a new version within the 90-day window.

A pinned version is never served by the fallback, so when its GPU capacity is unavailable you get `503` instead of an answer. See [Determinism](/docs/concepts/determinism/#scope).

## List models

`GET /v1/models` lists the alias, the exact versions and the fallback versions. Any valid API key can call it.

```bash
curl https://api.thinqit.ai/v1/models \
  -H "authorization: Bearer $DEX_API_KEY"
```

Each entry looks like this alias entry from the contract example:

```json
{
  "id": "dex-1",
  "object": "model",
  "kind": "alias",
  "target": "dex-1.0.0",
  "served_by": "gpu",
  "status": "active",
  "deterministic": true,
  "released_at": "2026-10-15T00:00:00Z",
  "retires_at": null,
  "calibration": "cal-20261015-1",
  "upstream": null,
  "limits": {
    "max_state_tokens": 16384,
    "max_question_tokens": 4096,
    "max_total_tokens": 16384,
    "max_questions": 32,
    "max_options": 255,
    "max_levels": 10,
    "exact_option_probabilities": 255
  },
  "quality": null
}
```

| Field | Meaning |
| --- | --- |
| `kind` | `alias` or `version`. |
| `target` | For an alias, the exact version it resolves to. |
| `served_by` | `gpu` or `fallback`. |
| `status` | `active`, `deprecated` or `retired`. |
| `deterministic` | `true` when the same request always gives the same answers from this version. |
| `released_at`, `retires_at` | When the version was released and when it retires (`null` when no date is set). |
| `calibration` | The calibration version applied. |
| `upstream` | For a fallback version, the hosted model and region that serve it. |
| `limits` | The request limits for this version. See [Limits](/docs/reference/limits/#model-limits). |
| `quality` | Published agreement and ECE figures with a link to the calibration report, or `null`. |

The full schema is in the [API reference for listModels](/docs/api/listModels/).