Train (or re-tune)

Train the model or re-tune it. From draft, a first call runs a full training pass and moves the model to ready. From ready, set reoptimize_params=true to run a fresh parameter search; without it the call is a no-op, since routine retraining on new samples happens automatically. Returns 202 with a run id once enqueued; a matching in-flight run returns 409 with its id in X-Run-Id.

POST /models/{handle}/train

cURL

cURL

curl -X POST https://u22a8.ai/v1/models/acme.support-tone/train \
  -H "Authorization: Bearer $U22A8_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"effort": "medium"}'

200

{
  "state": "<string>",
  "run_id": "<string>"
}

Asynchronous: a first train from draft returns 202 with a run id and moves the model through busy to ready. Poll GET …/models/{handle} for the state. From a ready model, pass reoptimize_params: true to force a fresh parameter search; otherwise routine retraining on new samples happens automatically.

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

POST /v1/models/{handle}/train body. All fields optional.

From draft, starts a first training pass (the model moves to busy, then ready). From ready with reoptimize_params=True, runs a fresh parameter search. From ready without it, a no-op — routine retraining on new samples runs automatically.

effort · string | null

How much cost and time to spend tuning: low|medium|high|max. Higher levels search more thoroughly. Ignored for automatic retraining.

reoptimize_params · boolean · default: false

When True, force a fresh parameter search from a ready model. When False, a ready model is a no-op (automatic retraining handles incremental updates).

Response

200

application/json

Successful Response

Response from POST /v1/models/{handle}/train.

state · string · required

Current model state after the call.

Examples:

"busy"

"ready"

run_id · string | null

Newly enqueued run id, or the matching existing run id on an idempotent hit. null when state == 'ready' and no re-optimization was requested (no run was queued).