Create a model

Create a draft model. handle is required and must be in a namespace your key owns — there is no auto-minting. kind is reserved-now and only accepts scoring at launch.

POST /models

cURL

cURL

curl -X POST https://u22a8.ai/v1/models \
  -H "Authorization: Bearer $U22A8_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"handle": "acme.support-tone", "description": "Warmth and clarity of support replies"}'

201

{
  "handle": "<string>",
  "scoring_method": "<string>",
  "description": "",
  "state": "ready",
  "kind": "scoring",
  "traits": [
    "<string>"
  ],
  "current_version_id": 123,
  "version_no": 123,
  "version_tags": [
    "<string>"
  ],
  "zero_data_retention": false,
  "last_operation": {
    "kind": "train",
    "run_id": "run_abc",
    "started_at": "2026-05-19T12:00:00Z",
    "status": "succeeded"
  }
}

Creates a model in the draft state. The handle must be in a namespace your key owns. Next: add traits and samples, then train.

Authorizations

Authorization · string · header · required

API key issued in the platform console, sent as Authorization: Bearer <key>.

Body

application/json

POST /v1/models body. handle is required and must be in a namespace the caller's key owns.

handle · string · required

Namespaced handle, <namespace>.<name> (e.g. u22a8.foo). Required — there is no auto-minting. The namespace must be one your key owns. Want a random handle? Generate the string yourself.

Example:

"u22a8.my-model"

description · string · default: ""

scoring_method · string · default: balanced_cosine

Example:

"balanced_cosine"

max_depth · integer · default: 1

kind · string · default: scoring

Model kind. Only scoring is accepted at launch — future kinds (classification/conformance/retrieval) land additively.

additional_terms · string | null

upstream_sources · Upstream Sources · object[] | null

readme_markdown · string | null

zero_data_retention · boolean · default: false

Enable zero-data-retention. When True, samples are purged at every training completion, automatic retraining is disabled, and POST /score with a feedback block is rejected.

Response

201

application/json

Successful Response

handle · string · required

Example:

"u22a8.compelling-readme"

scoring_method · string · required

Example:

"balanced_cosine"

description · string · default: ""

state · string · default: ready

Lifecycle state: draft, busy, ready, failed, or archived. busy is the transient state while an asynchronous operation (training, discovery, retraining) runs — see last_operation for which one.

Examples:

"draft"

"busy"

"ready"

"failed"

"archived"

kind · string · default: scoring

Example:

"scoring"

traits · string[]

Example:

["Clarity", "Flow"]

current_version_id · integer | null

Identifier of the version currently serving scores. Null before the first successful train; updates on every successful train or retrain.

version_no · integer | null

Version number of the active snapshot — the integer behind vN. Null before the first train.

version_tags · string[]

User-named tags pointing at the active version.

zero_data_retention · boolean · default: false

Whether zero-data-retention is enabled. When on, submitted content is not retained.

last_operation · Last Operation · object

The most recent lifecycle operation: {kind, status, started_at, run_id?, progress?, error?}. kind identifies what the model is doing while busy (e.g. train, discover, retrain). Null on models that have never run an operation.

Example:

{
  "kind": "train",
  "run_id": "run_abc",
  "started_at": "2026-05-19T12:00:00Z",
  "status": "succeeded"
}