Register and reuse schemas

Register a schema when multiple requests should use the same output contract. Registration validates and compiles the definition once, gives it a version, and returns an identifier. Later requests send that schema_id instead of repeating the schema.

Use an inline schema while exploring or for a one-off task. Registration is optional; it does not change what the schema means.

Run the complete workflow

This complete example uses a two-field message classification schema. Save it as triage.schema.json:

triage.schema.json

Download triage.schema.json

{
  "type": "object",
  "properties": {
    "department": {
      "type": "string",
      "enum": ["billing", "technical", "other"],
      "description": "Route charges, invoices and refunds to billing. Route broken product behavior to technical. Use other for anything else."
    },
    "duplicate": {
      "type": "boolean",
      "description": "True only when the message explicitly reports being charged more than once for the same purchase."
    }
  },
  "required": ["department", "duplicate"],
  "additionalProperties": false
}

The following client loads the schema file, calls POST /v1/schemas, saves the returned schema_id, and uses that ID for two POST /v1/resolve calls. The cURL version uses jq to read the ID and safely construct the request bodies.

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
from pathlib import Path
import httpx

with httpx.Client(
    base_url="https://api.blatent.ai",
    headers={"Authorization": f"Bearer {os.environ['BLATENT_API_KEY']}"},
    timeout=195,
) as client:
    registration = client.post("/v1/schemas", json={
        "name": "support/triage",
        "version": "0.0.1",
        "schema": json.loads(Path("triage.schema.json").read_text(encoding="utf-8")),
    })
    registration.raise_for_status()
    schema_id = registration.json()["schema_id"]

    for message in [
        "The invoice was charged twice. Can you help me get the duplicate charge refunded?",
        "The app crashes every time I open my settings."
    ]:
        response = client.post("/v1/resolve", json={
            "input": message, "schema_id": schema_id,
        })
        response.raise_for_status()
        print(json.dumps(response.json()["output"]))

TypeScript

import { readFileSync } from "node:fs";

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

for (const input of [
  "The invoice was charged twice. Can you help me get the duplicate charge refunded?",
  "The app crashes every time I open my settings."
]) {
  const response = await fetch(base + "/v1/resolve", {
    method: "POST", headers, signal: AbortSignal.timeout(195_000),
    body: JSON.stringify({ input, schema_id }),
  });
  if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  console.log(JSON.stringify((await response.json()).output));
}

cURL

set -eu

body=$(jq -n --slurpfile schema 'triage.schema.json' \
  '{name: "support/triage", version: "0.0.1", schema: $schema[0]}')
registration=$(curl --fail-with-body --silent --show-error \
  "https://api.blatent.ai/v1/schemas" \
  -H "Authorization: Bearer $BLATENT_API_KEY" \
  -H 'Content-Type: application/json' --data-binary "$body")
schema_id=$(printf '%s' "$registration" | jq -er '.schema_id')

while IFS= read -r input; do
  body=$(jq -n --arg input "$input" --arg id "$schema_id" \
    '{input: $input, schema_id: $id}')
  response=$(curl --fail-with-body --silent --show-error \
    "https://api.blatent.ai/v1/resolve" \
    -H "Authorization: Bearer $BLATENT_API_KEY" \
    -H 'Content-Type: application/json' --data-binary "$body")
  printf '%s' "$response" | jq -c '.output'
done <<'INPUTS'
The invoice was charged twice. Can you help me get the duplicate charge refunded?
The app crashes every time I open my settings.
INPUTS

Python and TypeScript print each generated output. The returned identifier selects the compiled server-side schema.

Illustrative printed outputs, one per input:

{"department":"billing","duplicate":true}
{"department":"technical","duplicate":false}

Reuse across processes

Store the returned schema_id in application configuration. On later application starts, send it directly to /v1/resolve; do not register again for each message. Keep the schema file in source control alongside the code that uses it.

Registration compiles the schema. It does not guarantee every execution cache is warm; measure first use and repeated requests separately.

Publish a change

A name and version identify immutable content. Re-registering the same definition at the same version is safe. Different content at that version returns 409 VERSION_CONFLICT.

Change the version for any schema or description edit. Test the new version, then update the configured ID or move a schema alias. Pin versions or digests when reproducibility matters.

Your schema version, such as 0.0.1, is independent of the API and documentation versions. The registry reference lists naming rules and response fields.

State and policies can accompany a registered schema just as they can an inline schema. See application state and OPA.