Update a model

PATCH /models/{handle}

cURL

cURL

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

200

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

Patches model metadata; omitted fields are left unchanged. Lifecycle state is not patchable — use POST …/train to move a draft to ready and DELETE to archive.

Authorizations

Authorization · string · header · required

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

Path Parameters

handle · string · required

Model handle, e.g. 'u22a8.technical-writing'.

Example:

"u22a8.technical-writing"

Body

application/json

PATCH /v1/models/{handle} body. Missing fields mean no change.

state is intentionally not patchable: move a model with POST /train (draft → ready) or DELETE (archive), never a PATCH override. Unknown fields (including state) are rejected so the contract is explicit rather than a silent no-op.

description · string | null

scoring_method · string | null

max_depth · integer | null

additional_terms · string | null

upstream_sources · Upstream Sources · object[] | null

readme_markdown · string | null

zero_data_retention · boolean | null

Toggle zero-data-retention. Turning it on purges existing samples. Turning it off applies going forward only — earlier purges are not reversed.

version_retention_policy · Version Retention Policy · object

Auto-prune policy override. Keys: keep_unnamed (int, default 100), keep_first_of_month (bool, default True). Null clears the override and reverts to defaults.

Example:

{
  "keep_first_of_month": true,
  "keep_unnamed": 50
}

Response

200

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