upsert alias
upsert_aliasCreate or repoint a model alias to shift production traffic to a new model without redeploying, while optionally adding canary, quality gate, or evidence policy controls.
Instructions
Create or repoint a model alias by name (idempotent upsert) so production traffic moves to a new model without a redeploy; optionally attach a canary split, a quality gate, or an evidence-required policy. PUT /v1/aliases (API-key scope: aliases:write). Returns: 200 with the alias object: { id, name, target_model, canary_model, canary_percent, description, gate_criterion_id, gate_mode, gate_min_samples, gate_rollback_threshold, gate_window_hours, gate_verdict, gate_verdict_at, model_version_id, require_evidence, last_evidence_run_id, created_at, updated_at } Notes: MOVES PRODUCTION TRAFFIC: the gateway resolves aliases within ~10s. Requires the key's minting user to be workspace OWNER/ADMIN (403 otherwise). Same status 200 whether created or updated. 412 Precondition Failed (code precondition_failed) when the evidence policy refuses the repoint; a brand-new alias is never blocked by the policy. 400 for schema failures, canary_percent > 0 without canary_model, canary equal to target, unavailable model, gate criterion never aligned, or auto-mode eligibility refusals (judge not trustworthy, drift-flagged, trace-unit, or judge trained the destination). 404 "Gate criterion not found". Billing always follows the model that actually ran; an alias is routing only.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Alias name, 3..64 chars of letters/digits/dots/dashes/underscores, must start and end alphanumeric, no '/'. Upsert key within the workspace. | |
| gate_mode | No | "recommend" (default) only surfaces verdicts; "auto" lets the gate repoint the alias itself and requires a trustworthy, non-drift-flagged, request-unit judge that did not train the destination model. | |
| description | No | Free-text note, max 200 chars (nullable). | |
| canary_model | No | Model id for the canary arm (nullable). Must differ from target_model and be an available model. Required (non-null) whenever canary_percent > 0. | |
| target_model | Yes | Model id that receives the main share of traffic. Must be an available model or the call fails with "Model '<id>' is not available." | |
| canary_percent | No | Integer 0..100 share of traffic sent to canary_model. Default 0. Ignored (stored as 0) when canary_model is null. | |
| override_reason | No | Audited escape hatch for the evidence policy: a written justification of at least 10 characters lets the repoint through and records an audit event. Blank/missing is NOT an override. Shorter than 10 chars is a 400. | |
| gate_min_samples | No | Scored requests both arms need before a verdict. Integer 10..1000, default 50. | |
| require_evidence | No | Evidence policy. Omitted = leave the existing alias's setting unchanged (false on create). When on, a repoint that sends traffic to a model it is not already reaching is refused unless a finished comparison in the last 30 days proves the destination against the incumbent. | |
| gate_criterion_id | No | Id of a criterion in this workspace that scores both arms online. Null = no gate. The criterion must have been aligned at least once. | |
| gate_window_hours | No | Trailing window of online scores a verdict is computed over. Integer 1..720, default 168. | |
| gate_rollback_threshold | No | Roll back when the canary's upper CI bound on pass rate is below this. Number 0..1, default 0.7. |