---
title: "Create a pod"
method: POST
path: "/v1/pods"
tags: ["Pods"]
---

# Create a pod

`POST /v1/pods`

Compute-fabric pod (BYO container image + SSH keys): a hardened GPU container on a whole native-driver GPU. Admission claims a free device-request GPU unit (see listPodCapacity for what is claimable), snapshots the on-demand rate immutably onto the pod, and drives the guest workflow.

## Request body

- CreatePodRequest — Request to create a compute-fabric pod: a RunPod-style bring-your-own container image + SSH keys guest. A focused subset of CreateVmRequest (no qcow2 template / kernel modules / privileged mode).
  - `computeClass` 'on_demand' | 'reserved' | 'interruptible' — purchase option. on_demand (pay per second, no commitment) is the only class sold; reserved is a deprecated alias that is stored as on_demand. interruptible is retired and rejected with 400 COMPUTE_CLASS_RETIRED; it remains listed only until the deprecation window closes.
  - `envVars` object
  - `gpuCount` integer — how many whole GPUs this pod gets. All of them are claimed on ONE node and passed to the container together; the pod is priced for gpuCount GPUs. Omitted = 1. A request larger than any single node can currently tile is rejected at admission (see freeUnits / maxGpuCount on /v1/pods/capacity).
  - `gpuModelId` string
  - `httpPort` integer — in-guest HTTP port exposed on the endpoint
  - `image` string, required — tenant container image ref (required)
  - `name` string
  - `public` boolean — true = open endpoint (no data-plane auth); default false requires an org API key
  - `shmSizeGb` integer — size of the pod's private /dev/shm in GiB (docker --shm-size). Optional; omitted lets the platform pick a safe default (a generous share for a pod that owns its whole node, otherwise 2 GiB per GPU). The maximum a create may set is the pod's memory entitlement on its placement node (its GPU-proportional share of node RAM); a larger value is rejected at admission. Raise this when a multi-GPU NCCL / PyTorch DataLoader workload needs more shared memory than the default.
  - `sshKeys` string[] — tenant SSH public keys injected into the guest

## Response `200`

Created

- VmSummary
  - `capabilityTier` string — compute-fabric capability tier (e.g. "pod"); empty for a plain VM
  - `computeClass` string — compute-fabric purchase option (on_demand; pods created before the rename carry the legacy reserved or interruptible values); empty for a plain VM
  - `createdAt` string
  - `diskSizeGb` integer
  - `endpointUrl` string
  - `gpuCount` integer
  - `gpuModelId` string
  - `gpuModelName` string
  - `id` string, required
  - `imageUrl` string — tenant container image (pods)
  - `managedBy` string — platform owner of this row ("serving" = inference serving replica, read-only on customer surfaces); empty for a customer-launched VM
  - `name` string, required
  - `organizationId` string, required
  - `pricePerHourCents` integer
  - `provisioningStage` string
  - `public` boolean — true = open endpoint (no data-plane auth); false = require an org API key
  - `resourceSize` string
  - `serviceType` string — managed-service tag; empty for a plain VM
  - `status` string, required
  - `statusReason` string — human-readable cause for failed/stuck states
  - `tier` string

## Other responses

- `400` — The request is invalid
- `401` — Missing or invalid API key
- `403` — API key lacks the required scope

---

[API](https://skmtc.dev/openrelay/apis/openrelay-api.md) · [All operations](https://skmtc.dev/openrelay/apis/openrelay-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/openrelay/openrelay-api/revisions/3dc47c9667e8/schema)