Start instruction optimization job
Optimize saved question instructions from annotated examples; every question must have string instructions. The request returns 202 Accepted with a Location header to poll.
/v1/models/{workspace}/{model}/alignmentsAuthorization
Send a Modaic bearer token in the Authorization header.
Headers
A key between 8 and 255 characters. Reuse it only when retrying this exact request.
Path Parameters
User or organization workspace slug.
Model repository slug. The caller needs the route-specific repository access.
Body
Branch to optimize 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.
maxMetricCalls is a positive integer up to 1,000,000. Omit it to size the
budget from the validation split. A run can finish a few calls past the budget,
and final validation of the selected instructions is billed separately.
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",
"reflection": {
"seed": 42,
"minibatchSize": 8
}
}
Response
Instruction optimization job ID.
New commit when instruction optimization 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 optimization artifact, then starts a batch inference job at that exact commit for all examples. If it does not improve the model, no model commit is created.