Migrate from API v1

​

What changed at a glance

• The base URL moves from https://rest.runpod.io/v1 to https://api.runpod.io/v2. Update every request to the new host and version prefix.
• The OpenAPI schema also moves accordingly, from https://rest.runpod.io/v1/openapi.json to https://api.runpod.io/v2/openapi.json. Regenerate any client or tooling against the v2 schema.
• Authentication is unchanged. Continue to pass your Runpod API key as an HTTP Bearer token in the Authorization: Bearer RUNPOD_API_KEY header. You don’t need to change key management or scopes to call v2.

​

Endpoint mapping

​

Consolidated Pod lifecycle

curl --request POST \
  --url https://rest.runpod.io/v1/pods/{podId}/stop \
  --header 'Authorization: Bearer RUNPOD_API_KEY'

curl --request POST \
  --url https://api.runpod.io/v2/pods/{id}/action \
  --header 'Authorization: Bearer RUNPOD_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"action":"stop"}'

​

Request and response shape changes

​

Nested create bodies

• In v1, create bodies are flat, with top-level fields such as gpuCount, gpuTypeIds, imageName, containerDiskInGb, volumeInGb, env, and ports. The v2 CreatePodRequest is nested: name and image are required, GPU settings live under gpu: {id, count}, CPU settings under cpu, and storage under mounts. The cloud field defaults to SECURE, and you must set exactly one of gpu or cpu. See Create a Pod for the full request schema.
• Serverless endpoint creation changes more than its path. In v1, EndpointCreateInput requires a templateId. v2’s CreateEndpointRequest still supports templateId: you can create an endpoint from a template ID, or provide the container details directly with name, image, and gpu. When you create from a template, image is optional because the template supplies it. Worker and scaling settings nest under workers and scaling, replacing v1’s flat workersMin, workersMax, scalerType, and idleTimeout. See Create a Serverless endpoint for the full schema.
• Templates share the same container-field renames as Pods: v1’s imageName, containerDiskInGb, isPublic, and containerRegistryAuthId become image, disk, public, and a nested registry in v2. See Create a template.
• Network volume creation renames dataCenterId to dataCenter and adds an optional type field for selecting the storage tier (STANDARD or HIGH_PERFORMANCE). See Create a network volume.

​

Wrapped list responses

[
  { "id": "pod-1" },
  { "id": "pod-2" }
]

{
  "pods": [
    { "id": "pod-1" },
    { "id": "pod-2" }
  ]
}

​

RFC 9457 error objects

{
  "message": "Pod not found"
}

{
  "title": "Not Found",
  "status": 404,
  "detail": "The requested Pod does not exist."
}

​

New in v2

• The v2 API adds capabilities that have no v1 equivalent.
• Catalog endpoints let you browse available compute without provisioning it: GET /v2/catalog/gpus and /gpus/{id}, /cpus and /cpus/{id}, and /datacenters and /datacenters/{id}. See List GPU types.
• Pod log streaming exposes GET /v2/pods/{id}/logs so you can follow a Pod’s output over the API. See Stream Pod logs.
• Serverless observability adds worker and release visibility through GET /v2/serverless/{id}/workers, /workers/{workerId}/logs, and /releases. See List Serverless endpoint workers, Stream Serverless worker logs, and List Serverless endpoint releases.
• Registry ECR delegations manage delegated registry access with GET and POST /v2/registries/delegations and DELETE /v2/registries/delegations/{id}. These endpoints aren’t yet covered by a dedicated reference page during beta; consult the v2 OpenAPI schema for their request and response formats.
• Expanded billing adds an aggregated history at GET /v2/billing alongside Serverless, Public Endpoint, and Instant Clusters histories, going beyond v1’s Pods, endpoints, and network volume breakdowns. See Get aggregated billing history.

​

Next steps