What changed at a glance
The base URL moves fromhttps://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.
Because v2 is in beta, endpoints and behavior may still change before general availability. Pin the specific endpoints you depend on and watch for updates as v2 stabilizes.
Endpoint mapping
Most resources keep the same concept but move to a new path. The following table maps each v1 resource to its v2 path.
Multi-word resources use kebab-case in v2, so
/networkvolumes becomes /v2/network-volumes. v2 also generalizes path parameters: where v1 used resource-specific names such as {podId}, {endpointId}, {networkVolumeId}, {templateId}, and {containerRegistryAuthId}, v2 uses a single generic {id} parameter across resources.
Consolidated Pod lifecycle
In v1, each Pod state change had its own endpoint:POST /pods/{podId}/start, /stop, /reset, and /restart. In v2, these collapse into a single Pod state transition endpoint, POST /v2/pods/{id}/action, whose request body carries the desired action as {"action":"start|stop|restart|terminate"}. Deletion still uses DELETE /v2/pods/{id}.
The v1
reset operation has no v2 action equivalent. The v2 action enum is limited to start, stop, restart, and terminate.POST /pods/{podId}/update with a standard PATCH request to PATCH /v2/pods/{id}. Serverless follows the same pattern: v2 drops v1’s POST /endpoints/{id}/update in-place variant in favor of PATCH /v2/serverless/{id}.
The following example shows how stopping a Pod changes between versions.
/stop path, v2 sends the same POST .../action request for every lifecycle transition and selects the operation with the action field in the request body.
Request and response shape changes
The v2 request and response formats differ from v1. The most impactful changes are nested create bodies, wrapped list responses, and standardized error objects. Full field-by-field mapping is out of scope for this guide; see the linked reference pages for complete schemas.Nested create bodies
In v1, create bodies are flat, with top-level fields such asgpuCount, 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. In v2, CreateEndpointRequest drops templateId entirely and instead requires name, image, and gpu directly, with worker and scaling settings nested 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
In v1, list endpoints return a bare JSON array. In v2, list responses wrap the array in an object keyed by the resource name.GET /v2/pods returns {"pods":[...]}, Serverless returns {"endpoints":[...]}, templates return {"templates":[...]}, network volumes return {"networkVolumes":[...]}, and registries return {"registries":[...]}. See List Pods for a complete example.
RFC 9457 error objects
In v1, errors return a simple{"message":"..."} object. In v2, errors follow the RFC 9457 problem format with required title, status, and detail fields, plus an optional errors array of validation strings.
As in v1, Runpod returns a 403 when a valid API key lacks access to the requested resource—but in v2 that response now uses the problem format shown here.
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
API v2 overview
Review the v2 base URL, authentication, and available resources.
Create a Pod
See the nested v2 request schema for provisioning a Pod.
List Serverless endpoints
Query your Serverless endpoints with the wrapped v2 response.
List GPU types
Browse available GPU types with the new catalog endpoints.