> ## Documentation Index > Fetch the complete documentation index at: https://runpod-b18f5ded-lg-apiv2-new.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Create a pod > Creates a new pod. Specify `gpu` for compute. ContainerConfig fields can be spread from a template response. ## OpenAPI ````yaml post /v2/pods openapi: 3.0.3 info: title: RunPod REST API version: 2.0.0 description: RunPod public REST API — v2 servers: - url: / description: Current server security: - bearerAuth: [] paths: /v2/pods: post: tags: - Pods summary: Create a pod description: | Creates a new pod. Specify `gpu` for compute. ContainerConfig fields can be spread from a template response. operationId: createPod requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePodRequest' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/Pod' default: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: CreatePodRequest: allOf: - $ref: '#/components/schemas/ContainerConfig' - type: object required: - name - image description: | Request body for creating a pod. Exactly one of `gpu` or `cpu` must be set — enforced at the handler layer. For CPU pods, memory is derived by the API from the selected flavor's RAM multiplier; clients provide only CPU flavor and vCPU count. CPU pods support container disk and network volumes only; `mounts.persistent` is invalid when `cpu` is set. properties: name: type: string minLength: 1 example: my-training-pod mounts: $ref: '#/components/schemas/Mounts' gpu: $ref: '#/components/schemas/GpuConfig' cpu: $ref: '#/components/schemas/CreateCpuConfig' cloud: $ref: '#/components/schemas/Cloud' dataCenterIds: type: array items: type: string description: | Preferred data centers for placement. Omit or pass an empty array to let the scheduler choose. example: - US-TX-3 globalNetworking: type: boolean default: false description: >- Enable global networking, giving the pod a private IP reachable across data centers. Requires an NVIDIA GPU and a global-networking-enabled data center (both enforced upstream). See `GET /v2/catalog/datacenters` (`globalNetwork`) for eligible data centers. example: false Pod: allOf: - $ref: '#/components/schemas/ContainerConfig' - type: object required: - id - name - status - actions - image - args - disk - mounts - ports - env - registry - cloud - dataCenterId - template - cost - locked - tags - runtime - createdAt - startedAt - globalNetworking properties: id: type: string example: pod_abc123 name: type: string example: my-training-pod status: $ref: '#/components/schemas/PodStatus' actions: type: array description: Valid state transitions for the current status. items: $ref: '#/components/schemas/PodAction' mounts: $ref: '#/components/schemas/Mounts' gpu: description: Present for GPU pods; omitted from CPU pods. allOf: - $ref: '#/components/schemas/GpuConfig' cpu: description: Present for CPU pods; omitted from GPU pods. allOf: - $ref: '#/components/schemas/CpuConfig' cloud: $ref: '#/components/schemas/Cloud' dataCenterId: type: string nullable: true description: Data center where the pod is running (assigned by scheduler) example: US-TX-3 template: type: string nullable: true description: ID of the template this pod was created from example: null cost: type: number format: float description: Current cost in USD per hour (0.0 when EXITED or TERMINATED) example: 0.35 locked: type: boolean description: Whether the pod is locked (prevents stopping or resetting) example: false globalNetworking: $ref: '#/components/schemas/PodGlobalNetworking' tags: type: array description: Tags attached to this pod. items: $ref: '#/components/schemas/Tag' runtime: nullable: true description: Live utilization metrics. Null when the pod is not RUNNING. allOf: - $ref: '#/components/schemas/PodRuntime' createdAt: type: string format: date-time example: '2026-03-13T20:00:00Z' startedAt: type: string format: date-time nullable: true example: '2026-03-13T20:00:00Z' ErrorResponse: type: object properties: title: type: string description: Short human-readable summary example: Not Found status: type: integer description: HTTP status code example: 404 detail: type: string description: Human-readable explanation example: pod not found ContainerConfig: type: object description: > Reusable container configuration shared across templates, pods, and serverless endpoints. Adding a field here automatically propagates to all three resources. properties: image: type: string description: Docker image reference example: runpod/pytorch:2.8.0-py3.11-cuda12.8.1 args: type: string description: Arguments passed to the container entrypoint example: '' disk: type: integer minimum: 1 description: Container disk in GB (ephemeral, wiped on restart) example: 50 ports: type: array description: Exposed ports, formatted as port/protocol items: type: string example: - 8888/http - 22/tcp env: type: object additionalProperties: type: string description: Environment variables as key-value pairs example: JUPYTER_PASSWORD: hunter2 registry: type: string nullable: true description: Container registry credential ID (for private images) example: null Mounts: type: object additionalProperties: false description: | Storage mounts attached to a pod. At-most-one of `persistent` or `network` may be set today (mutually exclusive, enforced at the handler with 400 if both are present). The `network` field is an array for forward compatibility with eventual multi-network-volume support, but `maxItems` is 1 today. PATCH semantics: - Omitting `mounts` or sending `{}` leaves the existing mount unchanged. - An explicit `network: []` is rejected with 400 (clearing mounts is not supported). - Mount kind is fixed at create — a PATCH that introduces a kind not present at create (persistent on a network pod, network on a persistent pod, or any mount on a previously-mountless pod) is rejected with 400. - The `volumeId` of a network mount is immutable; a PATCH that names a different `volumeId` is rejected with 400. - Partial mounts are not supported — every mount entry must include the full schema (`size` + `path` for persistent, `volumeId` + `path` for network). Missing required fields → 422. properties: persistent: $ref: '#/components/schemas/PersistentMount' network: type: array maxItems: 1 items: $ref: '#/components/schemas/NetworkMount' GpuConfig: type: object required: - id properties: id: type: string description: GPU type identifier example: NVIDIA GeForce RTX 4090 count: type: integer minimum: 1 default: 1 description: Number of GPUs example: 1 CreateCpuConfig: allOf: - $ref: '#/components/schemas/BaseCpuConfig' Cloud: type: string description: | Cloud tier. - `SECURE` — RunPod-owned datacenter hardware - `COMMUNITY` — community-hosted hardware - `ALL` — eligible for either tier (request-only; responses always report the concrete tier the pod was placed on) enum: - SECURE - COMMUNITY - ALL PodStatus: type: string description: | Lifecycle status of a pod. - `PROVISIONING` — pod is being allocated - `STARTING` — container is starting - `RUNNING` — container is healthy - `EXITED` — container exited (stopped) - `ERROR` — container is in an unrecoverable error state - `TERMINATED` — pod has been permanently deleted enum: - PROVISIONING - STARTING - RUNNING - EXITED - ERROR - TERMINATED PodAction: type: string description: State transition to trigger on a pod. enum: - start - stop - restart - terminate CpuConfig: allOf: - $ref: '#/components/schemas/BaseCpuConfig' - type: object required: - memory properties: memory: type: integer minimum: 1 description: Memory allocated to the pod in GB. example: 16 PodGlobalNetworking: type: object required: - enabled properties: enabled: type: boolean description: >- Whether global networking is enabled, giving the pod a private IP reachable across data centers. Derived from whether the pod has an assigned global-network address. example: true ip: type: string description: The pod's assigned global-networking IP. Present only when enabled. example: 10.65.1.42 internalDns: type: string description: >- Internal DNS name (`.runpod.internal`), reachable from other globally-networked pods in the same account. Present only when enabled. example: gfj8b292vyg08g.runpod.internal Tag: type: object required: - id - key - value additionalProperties: false properties: id: type: string description: Tag identifier example: tag_abc123 key: type: string minLength: 1 description: Tag key example: project value: type: string minLength: 1 description: Tag value example: gpt-training resources: type: array description: >- Populated only on direct tag responses when `?include=resources` is provided; omitted when the tag appears nested in another resource or if no resources have the tag. items: $ref: '#/components/schemas/TaggedResource' PodRuntime: type: object description: Live utilization metrics for a running pod. properties: uptime: type: integer description: Seconds since the container started example: 3600 gpus: type: array items: $ref: '#/components/schemas/PodGpuUtilization' cpu: $ref: '#/components/schemas/Utilization' memory: $ref: '#/components/schemas/Utilization' ports: type: array items: $ref: '#/components/schemas/PodRuntimePort' PersistentMount: type: object required: - size - path additionalProperties: false description: | Host-local persistent storage. Pinned to the pod's host machine — data does not survive a host failure. Disallowed on CPU pods. Mutually exclusive with NetworkMount. Deprecated: prefer NetworkMount for any data you cannot recreate. properties: size: type: integer minimum: 10 description: >- Host-local persistent storage in GB. Upstream enforces a 10 GB floor. example: 20 path: type: string description: Mount path inside the container. May be changed via PATCH. example: /workspace NetworkMount: type: object required: - volumeId - path additionalProperties: false description: | Reference to a NetworkVolume. Custom paths are honored at runtime on both GPU and CPU pods. The underlying `volumeId` is immutable post-create; the mount `path` may be changed via PATCH. properties: volumeId: type: string description: ID of an existing NetworkVolume in the same data center as the pod. example: vol_xyz path: type: string description: >- Mount path inside the container. No default — must be specified explicitly. example: /runpod-volume BaseCpuConfig: type: object required: - id - vcpuCount properties: id: type: string description: CPU flavor identifier, as returned by GET /v2/catalog/cpus. example: cpu5c minLength: 1 vcpuCount: type: integer minimum: 2 description: >- Number of vCPUs. Must be valid for the selected CPU flavor and must be a power of two. example: 4 TaggedResource: type: object required: - id - type additionalProperties: false properties: id: type: string description: Resource identifier. example: pod_abc123 type: $ref: '#/components/schemas/TagResourceType' PodGpuUtilization: type: object description: Per-GPU utilization metrics. properties: util: type: integer example: 94 memoryUtil: type: integer example: 78 Utilization: type: object description: >- Single-value utilization percentage (0–100). Shared by `cpu` and `memory`. properties: util: type: integer example: 45 PodRuntimePort: type: object description: Live port mapping for a running pod. properties: private: type: integer example: 8888 public: type: integer nullable: true example: 43210 type: type: string example: http ip: type: string nullable: true example: 45.23.12.1 TagResourceType: type: string description: Resource type attached to a tag. enum: - POD - NETWORK_VOLUME - CLUSTER - SERVERLESS_ENDPOINT example: POD securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: RunPod API Key ````