Concepts

If you haven't yet, read the short primer in Deployments & promotions. This page covers the API-level detail: exactly which statuses you'll see, how deployment_type is chosen, and how readiness is reported.

The promotion flow

Promoting a training creates a deployment record and starts serving it in the background. The status field walks through:

deploying → initializing → starting → deployed
                                    ↘ failed

failed, inactive, and archived are terminal: once recorded, the API reports them regardless of what live serving momentarily looks like, and ready is always false. Everything else is transient — the API prefers the live serving state when it has one, so a deployment moves to ready the moment it actually loads.

Shared vs Dedicated serving

Every deployment runs in one of two modes:

• Shared — your model serves from a multi-tenant pool. No capacity to manage; the platform scales it. This is the default, and it bills per inference.
• Dedicated — your model gets reserved serving capacity that you scale explicitly. Requests aren't billed individually; the capacity itself is what you pay for. Dedicated serving is a plan feature — see Billing.

Foundation models serve from the platform's foundation serving pool. You promote them exactly the same way; the platform routes them automatically, as described next.

How deployment_type is chosen

The request field is deployment_type; the API accepts "shared", "dedicated", and "foundation". You rarely need to set it — the platform resolves it from the model's kind:

Foundation models can only run on foundation serving, so if you send "shared" or "dedicated" for a foundation pipeline, the platform silently corrects it. For custom and BYOM models your choice is respected; omitting the field defaults to Shared.

Unpromote vs delete

• Unpromote (POST /v1/deployments/pipelines/{pipeline_id}/unpromote) gracefully removes a pipeline from live serving. The deployment record survives with status inactive, so your history and audit trail stay intact. This is the routine way to take a model offline.
• Delete (DELETE /v1/deployments/{promotion_id}) force-removes one specific deployment: it tears down the serving resources and archives the record in the same call, regardless of state. Use it when a deployment is stuck or you want it gone now.

Readiness and health

Deployment responses carry two related fields:

• status — the lifecycle state above.
• ready — a boolean: is this deployment answering requests right now?

A deployment can be deployed but momentarily not ready (for example, right after a restart), and idle deployments may park and wake on the first request — still ready. Gate your traffic on ready, not on the status string.