Create Dedicated Run

Dispatch a dedicated full-FT prime-rl run on a registered PrimeCluster.

Access is gated by ClusterAllocation - the picker in training_service.create_dedicated_run rejects callers whose team/user has no matching allocation on a live PrimeCluster. When team_id is set the caller must additionally be a member of that team (mirrors the LoRA/shared dispatch path).

Config validation (validator schema, hub env ids, HF repo names, per-run GPU cap) runs sync so bad configs return 400 immediately. Cluster-side probes (GPU capacity, model cache) and the helm install run async in a Cloud Task; callers poll GET /api/v1/rft/runs/{run_id} for status transitions PENDING -> CREATING -> RUNNING (or FAILED with errorMessage on a cluster-side rejection).

POST /api/v1/training/runs

Create Dedicated Run

cURL

curl --request POST \
  --url https://api.primeintellect.ai/api/v1/training/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "config": {},
  "mode": "rl",
  "imageTag": "<string>",
  "sourceRef": "<string>",
  "name": "<string>",
  "teamId": "<string>",
  "wandbApiKey": "<string>",
  "hfToken": "<string>",
  "secrets": {},
  "volume": "<string>",
  "gpuType": "<string>"
}
'

201

{
  "runId": "<string>",
  "jobId": "<string>",
  "tokenValue": "<string>"
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

config · Config · object · required

Full prime-rl-style TOML, parsed to a dict. Same shape as prime-rl/examples/*/rl.toml; the platform splits it into trainer / orchestrator / inference subconfigs and bakes each into the corresponding pod's startup command.

mode · enum<string> · default: rl

Which prime-rl schema the config blob follows. 'rl' (default) is the RL mega-TOML (trainer + orchestrator + inference). 'sft' is the SFT mega-TOML (top-level model/data/optim blocks, trainer-only deployment): the validator validates it against SFTConfig and renders a trainer-only Helm release (no orchestrator, inference, or env-server pods). The caller declares the mode; the backend never sniffs the config shape.

Available options: rl, sft

imageTag · string | null

prime-rl container image tag on ghcr.io/primeintellect-ai/prime-rl. Omit to use the deployment default: the operator-configured RL_FFT_DEFAULT_IMAGE_TAG when set, otherwise the validator's pinned build for RL runs and main for SFT runs. An explicit value, including main, is always used as-is.

sourceRef · string | null

prime-rl git ref (branch, tag, or sha in the canonical PrimeIntellect-ai/prime-rl repo) the pods check out over the image's baked source at start, so a branch can be tested without building an image. The validator resolves it to a commit and validates the config against that commit's schema; the resolved sha is pinned on the run. Not generally available: only team runs (teamId) may send it, the team needs sourceRef access granted (contact support), and the backend needs RL_SOURCE_REF_ENABLED.

name · string | null

Optional human-readable run name

teamId · string | null

Owning team (defaults to caller's user)

wandbApiKey · string | null

W&B key. On the PENDING fast-path it's materialised straight into the run's k8s Secret. On the QUEUED path it's stashed AES-encrypted on the RFTRun row so the drainer can rebuild the same Secret at promotion time without re-prompting.

hfToken · string | null

HF token for gated/private model downloads. Same storage rules as wandbApiKey above.

secrets · Secrets · object | null

Arbitrary env-var secrets projected into trainer / inference / orchestrator / env-server pods (parity with the LoRA path). Keys must be uppercase POSIX env-var names (e.g. 'OPENAI_API_KEY'); WANDB_API_KEY / HF_TOKEN / PRIME_API_KEY are reserved — use the dedicated fields for those. Materialised into the per-run k8s Secret. Held encrypted on the RFTRun row only for the sync -> dispatch-task hop, then cleared once the run deploys (or on stop / delete / rollback); never returned by any read endpoint.

Show child attributes

volume · string | null

Name of a volume in the caller's team (or personal) namespace. The run writes its outputs to runs/<runId>/ on it instead of to a per-run PVC.

gpuType · string | null

Optional GPU type constraint (e.g. 'H200_141GB', 'B200_180GB'). When set, dispatch is restricted to PrimeClusters whose gpuType matches. When omitted, the picker chooses the oldest eligible cluster with no type preference.

Response

201

application/json

Successful Response

runId · string · required

jobId · string · required

tokenValue · string · required

PRIME_API_KEY for this run. Returned once — the platform stores only the token id.