Schema aliases

POST /v1/schema-aliases

An alias is a movable name for an existing schema version. Use versions or digests for reproducibility and an alias for a controlled rollout.

Request body

name string required

The schema name.

alias string required

A movable tag, such as production.

target string required

An existing release of the same schema.

expected_digest string | null optional

If supplied, must match the alias’s current digest.

The target must belong to the same schema name. A published version tag cannot be converted to an alias.

Create an alias

First register the target version, then:

Before you run this example

Call https://api.blatent.ai from your server. Set your API key in the same terminal where you run the example:

export BLATENT_API_KEY='YOUR_SERVICE_KEY'

Python requires Python 3.10+ and HTTPX:

python -m pip install "httpx>=0.28,<1"

TypeScript requires Node.js 24+ and uses its built-in fetch. The cURL examples require curl and jq.

Save the displayed files and the selected client in one directory. Run the client there with python example.py, node example.ts or bash example.sh. Downloads use the example's name in place of example.

Download Python

Python

import json
import os
import httpx

response = httpx.post(
    "https://api.blatent.ai" + "/v1/schema-aliases",
    headers={"Authorization": f"Bearer {os.environ['BLATENT_API_KEY']}"},
    json={
        "name": "support/triage",
        "alias": "production",
        "target": "support/triage:0.0.1",
    },
    timeout=195,
)
response.raise_for_status()
print(json.dumps(response.json()["schema_id"]))

TypeScript

const response = await fetch(
  "https://api.blatent.ai" + "/v1/schema-aliases",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.BLATENT_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "support/triage",
      alias: "production",
      target: "support/triage:0.0.1",
    }),
    signal: AbortSignal.timeout(195_000),
  },
);
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const body = await response.json();
console.log(JSON.stringify(body.schema_id));

cURL

curl --fail-with-body --silent --show-error \
  "https://api.blatent.ai/v1/schema-aliases" \
  -H "Authorization: Bearer $BLATENT_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @- <<'JSON'
{
  "name": "support/triage",
  "alias": "production",
  "target": "support/triage:0.0.1"
}
JSON

200 OK. The response contains schema_id and schema_digest. The new reference is support/triage:production.

Update without losing a concurrent change

Inspect the alias, capture its current schema_digest, then include that value as expected_digest in the update. A mismatch returns 409 VERSION_CONFLICT. Re-read and reconcile the change before retrying.

Without expected_digest, an alias update does not check its previous target. Invalid targets return 404; a target with a different schema name returns 422 SCHEMA_INVALID.

Rollout timing

After an alias moves, other API instances may continue resolving its previous target for up to 30 seconds. An in-flight request keeps the version selected when it started. Use an immutable version or digest reference when a request must use a specific revision; inspect schema_digest in the response to identify the revision used.