---
title: "Pre-deployment checks for a serving spec (platform admin)"
method: GET
path: "/v1/admin/inference/serving/preflight"
tags: ["Internal"]
---

# Pre-deployment checks for a serving spec (platform admin)

`GET /v1/admin/inference/serving/preflight`

Read-only. Evaluates everything that must already be true for a deployment with the given spec to admit, place, and register: the catalog row is seeded with pricing, the weights ref is published, the GPU footprint fits the serving capacity budget, prepared nodes exist, and readiness probing is configured. Each check is only applied when its query parameters are present, so the UI can preflight incrementally as a form is filled in.

## Query parameters

- `publicModelId` string
- `gpuModelId` string
- `gpuCountPerReplica` integer
- `replicasDesired` integer
- `weightsRef` string
- `nodePool` string
- `rolloutRole` '' | 'green'

## Response `200`

Preflight result

- ServingPreflight — Read-only pre-deployment checks: everything that must already be true for a serving deployment with the given spec to admit, place, and register. Every check the query parameters make applicable must pass for ok.
  - `capacity` ServingPreflightCapacity, required — The serving capacity budget, evaluated for the requested footprint.
    - `committedOtherGpus` integer — GPUs other active serving deployments of this model already commit
    - `evaluated` boolean, required — gpuModelId, gpuCountPerReplica and replicasDesired were all passed
    - `fleetTotalGpus` integer — Structural fleet size of this GPU model (free + claimed units on online nodes)
    - `laneCommittedGpus` integer — GPUs the target lane's existing live deployments already commit for this GPU model. Present only when publicModelId (and nodePool) were passed.
    - `ok` boolean, required — true when the footprint fits the budget (or the guard is disabled)
    - `reason` string — The hold reason dispatch would surface, when not ok
    - `requestedGpus` integer — replicasDesired x gpuCountPerReplica
    - `reserveGpus` integer — Customer reserve per GPU model (SERVING_CUSTOMER_RESERVE_GPUS); 0 = guard disabled
    - `rolloutOk` boolean — Whether rolloutPeakGpus fits the serving budget. This is a WARNING, not a blocker: `ok` still reflects the single-deployment verdict, because running a deliberately tight rollout and draining the old side as the new one ramps is a legitimate plan.
    - `rolloutPeakGpus` integer — Peak GPU demand while a rollout is in flight: requestedGpus plus laneCommittedGpus, because the old and new generations both hold real hardware until the old one is drained.
    - `rolloutReason` string — Why the rollout peak does not fit, in lane terms, when rolloutOk is false
  - `model` ServingPreflightModel, required — Catalog-row checks for the target public model.
    - `backendCount` integer — Backends already on the row (other providers, prior deployments)
    - `enabled` boolean
    - `found` boolean — The catalog row exists (the registrar refuses to create one)
    - `hasPricing` boolean — The row carries at least one pricing dimension; deployments must never invent a price
    - `provided` boolean, required — publicModelId was passed; the remaining fields are only meaningful when true
  - `nodes` ServingPreflightNodes, required — Node-prep checks for the requested GPU model.
    - `evaluated` boolean, required — gpuModelId was passed
    - `gpuNodeCount` integer — Active nodes with sellable units of this GPU model
    - `virtiofsdReadyCount` integer — Of those, Nomad-ready nodes carrying the vectorlay_virtiofsd meta. Weights-backed replicas can only place on these; a node enrolled before virtiofsd support must re-enroll. Absent when Nomad was not reachable or weightsRef was not passed (the constraint only applies to weights-backed VMs).
  - `ok` boolean, required
  - `poolKeyConfigured` boolean, required — OPENRELAY_POOL_API_KEY is set. Without it readiness probes return no verdicts and pool membership holds forever.
  - `weights` ServingPreflightWeights, required — Weights-distribution checks for the requested weightsRef.
    - `configured` boolean, required — The weights distributor is wired on this control plane (S3_WEIGHTS_BUCKET)
    - `digest` string
    - `provided` boolean, required — weightsRef was passed
    - `published` boolean — The ref resolves to a digest in the weights manifest
    - `totalBytes` integer

## Other responses

- `401` — Missing or invalid API key
- `403` — API key lacks the required scope
- `503` — A required integration (e.g. payments) is not configured

---

[API](https://skmtc.net/openrelay/apis/openrelay-api.md) · [All operations](https://skmtc.net/openrelay/apis/openrelay-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/openrelay/openrelay-api/versions/32905b8f44f8/schema)