Start alignment
Start an asynchronous alignment for a model. Alignment learns from annotated training examples and selects improved instructions using the model's test split.
Each question must have string instructions for alignment. The more flexible
inference contract also permits omitted, null, or other JSON instructions, but
those must be replaced with strings before aligning. Criteria descriptions may
remain structured objects or arrays.
The endpoint returns 202 Accepted. Poll the URL in the Location response
header for progress.
/v1/models/{modelId}/alignmentsAuthorization
Send a Modaic bearer token in the Authorization header.
Parameters
A key between 8 and 255 characters. Reuse it only when retrying this exact request.
Model repository ID. Repository write access is required.
Branch to align and, when the run improves the model, update.
Current branch head, from 7 to 128 characters. The request returns
409 source_commit_conflict if the branch has advanced.
Contains maxMetricCalls, a positive integer up to 1,000,000. This is the
maximum number of example-question evaluations available to the run.
Optional reflection settings: model, positive minibatchSize up to 10,000,
and integer seed from 0 to 2,147,483,647.
Request example
{
"branch": "main",
"sourceCommitSha": "df5a6fb2d67e4ce6a6ea9d43146d53a4d43f6d37",
"budget": {
"maxMetricCalls": 500
},
"reflection": {
"seed": 42,
"minibatchSize": 8
}
}
Response
Alignment ID.
New commit when the alignment improves the model; otherwise null.
On completion, includes improved, the best candidate instructions, initial
and best scores, token usage, optional validation metrics, and the saved
artifact path.
Live progress with a stage, elapsed time, and—when available—metric-call,
iteration, candidate, and score counters.
Job-level error with code and message.
If the run improves the model, Modaic increments its checkpoint, commits the optimized instructions and alignment artifact, then starts a batch decision at that exact commit for all examples. If it does not improve the model, no model commit is created.