Models and versions

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#

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 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#

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 and the calibration reports.

Fallback versions#

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

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.

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.

List models#

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

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

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

{
  "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
}

The full schema is in the API reference for listModels.