docs: Add REST API v1 to v2 migration guide - #733
Conversation
Add a migration guide under the API v2 tab that maps v1 endpoints to their v2 equivalents, explains request/response shape changes for shared resources, and highlights the net-new v2 endpoints (catalog, log streaming, serverless observability, registry delegations, expanded billing). Add the page to the API v2 navigation group in docs.json.
![promptless[bot]](https://avatars.githubusercontent.com/in/979718?s=60&v=4){kind=small}
|
|
||
| ## 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. |
There was a problem hiding this comment.
v1 spec server URL is https://rest.runpod.io/v1.
Source:
docs/api-reference/openapi.json
Line 19 in 5328dc9
|
|
||
| ## 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. |
There was a problem hiding this comment.
v2 spec server URL is https://api.runpod.io, with paths prefixed /v2, giving an effective base of https://api.runpod.io/v2.
Source:
docs/api-reference-v2/openapi.json
Lines 8 to 12 in 5328dc9
| The Runpod REST API v2 reorganizes resource paths, consolidates Pod lifecycle actions, and standardizes request and response shapes. This guide maps the v1 surface you know to its v2 equivalent so you can update your integrations with confidence. | ||
|
|
||
| <Warning> | ||
| The REST API v2 is currently in beta. Endpoints and behavior may change before general availability. |
There was a problem hiding this comment.
v2 overview page confirms API v2 is currently in beta.
Source:
docs/api-reference-v2/overview.mdx
Lines 7 to 9 in 5328dc9
|
|
||
| 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](/get-started/api-keys) 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. |
There was a problem hiding this comment.
v1 security scheme ApiKey is type http, scheme bearer.
Source:
docs/api-reference/openapi.json
Lines 2026 to 2031 in 5328dc9
|
|
||
| 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](/get-started/api-keys) 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. |
There was a problem hiding this comment.
v2 security scheme bearerAuth is type http, scheme bearer, confirming auth is unchanged (Bearer + Runpod API key) between v1 and v2.
Source:
docs/api-reference-v2/openapi.json
Lines 50 to 56 in 5328dc9
| | Serverless billing | `/billing/endpoints` | `/v2/billing/serverless` | | ||
| | Network volume billing | `/billing/networkvolumes` | `/v2/billing/networkvolumes` | | ||
|
|
||
| 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. |
There was a problem hiding this comment.
v2 pods path uses a generic {id} path parameter (example pod_abc123), vs. v1's resource-specific {podId}/{endpointId}/{networkVolumeId}/{templateId}/{containerRegistryAuthId}.
Source:
docs/api-reference-v2/openapi.json
Lines 3891 to 3903 in 5328dc9
|
|
||
| ## 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](/api-reference-v2/pods/trigger-a-pod-state-transition), `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}`](/api-reference-v2/pods/terminate-a-pod). |
There was a problem hiding this comment.
v2 consolidated Pod lifecycle endpoint is POST /v2/pods/{id}/action with a PodActionRequest body carrying the action field.
Source:
docs/api-reference-v2/openapi.json
Lines 4243 to 4258 in 5328dc9
| 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](/api-reference-v2/pods/trigger-a-pod-state-transition), `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}`](/api-reference-v2/pods/terminate-a-pod). | ||
|
|
||
| <Note> | ||
| The v1 `reset` operation has no v2 action equivalent. The v2 action enum is limited to `start`, `stop`, `restart`, and `terminate`. |
There was a problem hiding this comment.
v2 PodAction enum is exactly start, stop, restart, terminate — reset is not included.
Source:
docs/api-reference-v2/openapi.json
Lines 1575 to 1584 in 5328dc9
| The v1 `reset` operation has no v2 action equivalent. The v2 action enum is limited to `start`, `stop`, `restart`, and `terminate`. | ||
| </Note> | ||
|
|
||
| For in-place changes to a Pod, v2 replaces v1's `POST /pods/{podId}/update` with a standard [PATCH request](/api-reference-v2/pods/update-a-pod) 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}`. |
There was a problem hiding this comment.
v1 has a dedicated POST /pods/{podId}/update endpoint (synonym for PATCH), dropped in v2 in favor of a single PATCH /v2/pods/{id}.
Source:
docs/api-reference/openapi.json
Lines 511 to 557 in 5328dc9
| The v1 `reset` operation has no v2 action equivalent. The v2 action enum is limited to `start`, `stop`, `restart`, and `terminate`. | ||
| </Note> | ||
|
|
||
| For in-place changes to a Pod, v2 replaces v1's `POST /pods/{podId}/update` with a standard [PATCH request](/api-reference-v2/pods/update-a-pod) 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}`. |
There was a problem hiding this comment.
v1 has a dedicated POST /endpoints/{endpointId}/update endpoint (synonym for PATCH); v2 drops this in-place-update path variant in favor of PATCH /v2/serverless/{id}.
Source:
docs/api-reference/openapi.json
Lines 901 to 920 in 5328dc9
|
|
||
| ### 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](/api-reference-v2/pods/create-a-pod) for the full request schema. |
There was a problem hiding this comment.
v1 PodCreateInput is a flat object with top-level gpuCount, gpuTypeIds, imageName, containerDiskInGb, volumeInGb, env, and ports fields.
Source:
docs/api-reference/openapi.json
Lines 2523 to 2966 in 5328dc9
|
|
||
| ### 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](/api-reference-v2/pods/create-a-pod) for the full request schema. |
There was a problem hiding this comment.
v2 CreatePodRequest requires name and image, nests gpu ({id,count}) and cpu configs, uses mounts for storage, and defaults cloud to SECURE; description states exactly one of gpu or cpu must be set.
Source:
docs/api-reference-v2/openapi.json
Lines 1787 to 1854 in 5328dc9
|
|
||
| ### 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. |
There was a problem hiding this comment.
v1 Pods schema (list response) is a bare array of Pod objects, not wrapped in an object.
Source:
docs/api-reference/openapi.json
Lines 2034 to 2039 in 5328dc9
|
|
||
| </CodeGroup> | ||
|
|
||
| The v2 wrapper key matches the resource: `GET /v2/pods` returns `{"pods":[...]}`, Serverless returns `{"endpoints":[...]}`, templates return `{"templates":[...]}`, network volumes return `{"networkVolumes":[...]}`, and registries return `{"registries":[...]}`. See [List Pods](/api-reference-v2/pods/list-pods) for a complete example. |
There was a problem hiding this comment.
v2 ListPodsResponse wraps the pod array under the "pods" key.
Source:
docs/api-reference-v2/openapi.json
Lines 1895 to 1908 in 5328dc9
|
|
||
| </CodeGroup> | ||
|
|
||
| The v2 wrapper key matches the resource: `GET /v2/pods` returns `{"pods":[...]}`, Serverless returns `{"endpoints":[...]}`, templates return `{"templates":[...]}`, network volumes return `{"networkVolumes":[...]}`, and registries return `{"registries":[...]}`. See [List Pods](/api-reference-v2/pods/list-pods) for a complete example. |
There was a problem hiding this comment.
v2 ListEndpointsResponse wraps the array under the "endpoints" key.
Source:
docs/api-reference-v2/openapi.json
Lines 899 to 912 in 5328dc9
|
|
||
| </CodeGroup> | ||
|
|
||
| The v2 wrapper key matches the resource: `GET /v2/pods` returns `{"pods":[...]}`, Serverless returns `{"endpoints":[...]}`, templates return `{"templates":[...]}`, network volumes return `{"networkVolumes":[...]}`, and registries return `{"registries":[...]}`. See [List Pods](/api-reference-v2/pods/list-pods) for a complete example. |
There was a problem hiding this comment.
v2 ListTemplatesResponse wraps the array under the "templates" key.
Source:
docs/api-reference-v2/openapi.json
Lines 2040 to 2053 in 5328dc9
|
|
||
| </CodeGroup> | ||
|
|
||
| The v2 wrapper key matches the resource: `GET /v2/pods` returns `{"pods":[...]}`, Serverless returns `{"endpoints":[...]}`, templates return `{"templates":[...]}`, network volumes return `{"networkVolumes":[...]}`, and registries return `{"registries":[...]}`. See [List Pods](/api-reference-v2/pods/list-pods) for a complete example. |
There was a problem hiding this comment.
v2 ListNetworkVolumesResponse wraps the array under the "networkVolumes" key.
Source:
docs/api-reference-v2/openapi.json
Lines 2173 to 2186 in 5328dc9
|
|
||
| </CodeGroup> | ||
|
|
||
| The v2 wrapper key matches the resource: `GET /v2/pods` returns `{"pods":[...]}`, Serverless returns `{"endpoints":[...]}`, templates return `{"templates":[...]}`, network volumes return `{"networkVolumes":[...]}`, and registries return `{"registries":[...]}`. See [List Pods](/api-reference-v2/pods/list-pods) for a complete example. |
There was a problem hiding this comment.
v2 ListRegistriesResponse wraps the array under the "registries" key.
Source:
docs/api-reference-v2/openapi.json
Lines 2236 to 2249 in 5328dc9
|
|
||
| ### 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. |
There was a problem hiding this comment.
v1 UnauthorizedError schema is a simple object with only a message string field, representative of v1's error shape.
Source:
docs/api-reference/openapi.json
Lines 4335 to 4342 in 5328dc9
|
|
||
| ### 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. |
There was a problem hiding this comment.
v2 ErrorResponse (RFC 9457 problem object) requires title, status, and detail, plus an optional errors array of validation-failure strings.
Source:
docs/api-reference-v2/openapi.json
Lines 3636 to 3678 in 5328dc9
|
|
||
| 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. |
There was a problem hiding this comment.
v2 ForbiddenError response documents a 403 when the bearer token is valid but lacks access to the requested resource or action.
Source:
docs/api-reference-v2/openapi.json
Lines 79 to 98 in 5328dc9
|
|
||
| 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](/api-reference-v2/catalog/list-gpu-types). |
There was a problem hiding this comment.
v2 catalog paths exist for /v2/catalog/gpus, /gpus/{id}, /cpus, /cpus/{id}, /datacenters (no hyphen), and /datacenters/{id} — net-new vs. v1.
Source:
docs/api-reference-v2/openapi.json
Lines 6236 to 6873 in 5328dc9
|
|
||
| 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](/api-reference-v2/catalog/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](/api-reference-v2/pods/stream-pod-logs). |
There was a problem hiding this comment.
v2 GET /v2/pods/{id}/logs is a net-new pod log streaming endpoint with no v1 equivalent.
Source:
docs/api-reference-v2/openapi.json
Lines 4146 to 4158 in 5328dc9
|
|
||
| Pod log streaming exposes `GET /v2/pods/{id}/logs` so you can follow a Pod's output over the API. See [Stream Pod logs](/api-reference-v2/pods/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](/api-reference-v2/serverless/list-serverless-endpoint-workers), [Stream Serverless worker logs](/api-reference-v2/serverless/stream-serverless-worker-logs), and [List Serverless endpoint releases](/api-reference-v2/serverless/list-serverless-endpoint-releases). |
There was a problem hiding this comment.
v2 adds net-new Serverless observability paths: /v2/serverless/{id}/workers, /workers/{workerId}/logs, and /releases.
Source:
docs/api-reference-v2/openapi.json
Lines 4868 to 5148 in 5328dc9
|
|
||
| Serverless observability adds worker and release visibility through `GET /v2/serverless/{id}/workers`, `/workers/{workerId}/logs`, and `/releases`. See [List Serverless endpoint workers](/api-reference-v2/serverless/list-serverless-endpoint-workers), [Stream Serverless worker logs](/api-reference-v2/serverless/stream-serverless-worker-logs), and [List Serverless endpoint releases](/api-reference-v2/serverless/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](/api-reference-v2/overview) for their request and response formats. |
There was a problem hiding this comment.
v2 adds net-new ECR delegation paths: GET/POST /v2/registries/delegations and DELETE /v2/registries/delegations/{id}.
Source:
docs/api-reference-v2/openapi.json
Lines 6112 to 6235 in 5328dc9
|
|
||
| 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](/api-reference-v2/overview) 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](/api-reference-v2/billing/get-aggregated-billing-history). |
There was a problem hiding this comment.
v2 adds a net-new aggregated billing history endpoint at GET /v2/billing.
Source:
docs/api-reference-v2/openapi.json
Lines 6874 to 6979 in 5328dc9
|
|
||
| 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](/api-reference-v2/overview) 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](/api-reference-v2/billing/get-aggregated-billing-history). |
There was a problem hiding this comment.
v1 billing breakdown is limited to /billing/pods, /billing/endpoints (Serverless billing), and /billing/networkvolumes.
Source:
docs/api-reference/openapi.json
Lines 1587 to 1728 in 5328dc9
|
|
||
| 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](/api-reference-v2/overview) 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](/api-reference-v2/billing/get-aggregated-billing-history). |
There was a problem hiding this comment.
v2 adds Serverless (/v2/billing/serverless), Public Endpoint (/v2/billing/endpoints), and Instant Cluster (/v2/billing/clusters) billing histories beyond the v1 breakdown.
Source:
docs/api-reference-v2/openapi.json
Lines 7079 to 7357 in 5328dc9
|
|
||
| | Resource | v1 path | v2 path | | ||
| | --- | --- | --- | | ||
| | Pods | `/pods` | `/v2/pods` | |
There was a problem hiding this comment.
v2 pods collection path is /v2/pods (v1 equivalent /pods confirmed at api-reference/openapi.json line 103).
Source:
docs/api-reference-v2/openapi.json
Line 3682 in 5328dc9
| | Resource | v1 path | v2 path | | ||
| | --- | --- | --- | | ||
| | Pods | `/pods` | `/v2/pods` | | ||
| | Serverless | `/endpoints` | `/v2/serverless` | |
There was a problem hiding this comment.
v2 serverless collection path is /v2/serverless (v1 equivalent /endpoints confirmed at api-reference/openapi.json line 683).
Source:
docs/api-reference-v2/openapi.json
Line 4384 in 5328dc9
| | --- | --- | --- | | ||
| | Pods | `/pods` | `/v2/pods` | | ||
| | Serverless | `/endpoints` | `/v2/serverless` | | ||
| | Templates | `/templates` | `/v2/templates` | |
There was a problem hiding this comment.
v2 templates collection path is /v2/templates (v1 equivalent /templates confirmed at api-reference/openapi.json line 948).
Source:
docs/api-reference-v2/openapi.json
Line 5149 in 5328dc9
| | Pods | `/pods` | `/v2/pods` | | ||
| | Serverless | `/endpoints` | `/v2/serverless` | | ||
| | Templates | `/templates` | `/v2/templates` | | ||
| | Network volumes | `/networkvolumes` | `/v2/network-volumes` | |
There was a problem hiding this comment.
v2 network volumes collection path is /v2/network-volumes (kebab-case; v1 equivalent /networkvolumes confirmed at api-reference/openapi.json line 1233).
Source:
docs/api-reference-v2/openapi.json
Line 5552 in 5328dc9
| | Serverless | `/endpoints` | `/v2/serverless` | | ||
| | Templates | `/templates` | `/v2/templates` | | ||
| | Network volumes | `/networkvolumes` | `/v2/network-volumes` | | ||
| | Registries | `/containerregistryauth` | `/v2/registries` | |
There was a problem hiding this comment.
v2 registries collection path is /v2/registries (v1 equivalent /containerregistryauth confirmed at api-reference/openapi.json line 1456).
Source:
docs/api-reference-v2/openapi.json
Line 5875 in 5328dc9
| | Templates | `/templates` | `/v2/templates` | | ||
| | Network volumes | `/networkvolumes` | `/v2/network-volumes` | | ||
| | Registries | `/containerregistryauth` | `/v2/registries` | | ||
| | Pod billing | `/billing/pods` | `/v2/billing/pods` | |
There was a problem hiding this comment.
v2 pod billing path is /v2/billing/pods (v1 equivalent /billing/pods confirmed at api-reference/openapi.json line 1587).
Source:
docs/api-reference-v2/openapi.json
Lines 6980 to 7078 in 5328dc9
| | Network volumes | `/networkvolumes` | `/v2/network-volumes` | | ||
| | Registries | `/containerregistryauth` | `/v2/registries` | | ||
| | Pod billing | `/billing/pods` | `/v2/billing/pods` | | ||
| | Serverless billing | `/billing/endpoints` | `/v2/billing/serverless` | |
There was a problem hiding this comment.
v2 serverless billing path is /v2/billing/serverless, summary "Get serverless billing history" (v1 equivalent /billing/endpoints confirmed at api-reference/openapi.json line 1729).
Source:
docs/api-reference-v2/openapi.json
Lines 7079 to 7179 in 5328dc9
| | Registries | `/containerregistryauth` | `/v2/registries` | | ||
| | Pod billing | `/billing/pods` | `/v2/billing/pods` | | ||
| | Serverless billing | `/billing/endpoints` | `/v2/billing/serverless` | | ||
| | Network volume billing | `/billing/networkvolumes` | `/v2/billing/networkvolumes` | |
There was a problem hiding this comment.
v2 network volume billing path is /v2/billing/networkvolumes (v1 equivalent /billing/networkvolumes confirmed at api-reference/openapi.json line 1964).
Source:
docs/api-reference-v2/openapi.json
Lines 7260 to 7356 in 5328dc9
| 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. | ||
|
|
||
| <Warning> | ||
| Billing paths don't map by name. In v1, `/billing/endpoints` returns Serverless billing history; in v2, Serverless billing moves to `/v2/billing/serverless`. The v2 path `/v2/billing/endpoints` is a different, new resource — Public Endpoint billing history — so update your Serverless billing calls to the new path rather than assuming the old one carries over. |
There was a problem hiding this comment.
v1 /billing/endpoints page is titled "Serverless billing history"; its OpenAPI summary is "Serverless billing history" (api-reference/openapi.json line 1729).
Source:
| 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. | ||
|
|
||
| <Warning> | ||
| Billing paths don't map by name. In v1, `/billing/endpoints` returns Serverless billing history; in v2, Serverless billing moves to `/v2/billing/serverless`. The v2 path `/v2/billing/endpoints` is a different, new resource — Public Endpoint billing history — so update your Serverless billing calls to the new path rather than assuming the old one carries over. |
There was a problem hiding this comment.
v2 /v2/billing/serverless summary is "Get serverless billing history" — confirms Serverless billing moves to this path in v2.
Source:
docs/api-reference-v2/openapi.json
Lines 7079 to 7179 in 5328dc9
| 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. | ||
|
|
||
| <Warning> | ||
| Billing paths don't map by name. In v1, `/billing/endpoints` returns Serverless billing history; in v2, Serverless billing moves to `/v2/billing/serverless`. The v2 path `/v2/billing/endpoints` is a different, new resource — Public Endpoint billing history — so update your Serverless billing calls to the new path rather than assuming the old one carries over. |
There was a problem hiding this comment.
v2 /v2/billing/endpoints summary is "Get public endpoint billing history" — a different resource than v1's /billing/endpoints (Serverless), confirming the two paths don't map by name.
Source:
docs/api-reference-v2/openapi.json
Lines 7180 to 7259 in 5328dc9
|
|
||
| ## 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. |
There was a problem hiding this comment.
v1 overview documents the OpenAPI schema URL as https://rest.runpod.io/v1/openapi.json.
Source:
docs/api-reference/overview.mdx
Line 33 in 5328dc9
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
Open this suggestion in Promptless to view citations and reasoning process
Adds a new migration guide (
api-reference-v2/migrate-from-v1.mdx) for developers moving an existing integration from the deprecated REST API v1 to the beta REST API v2, and links it in the API v2 navigation group.The guide covers the two things requested: the differences between v1 and v2 for endpoints that exist in both, and the net-new v2 endpoints.
For shared endpoints it explains the base URL change (
https://rest.runpod.io/v1→https://api.runpod.io/v2), that authentication is unchanged, the resource path renames (/endpoints→/serverless,/containerregistryauth→/registries,/networkvolumes→/network-volumes), the consolidation of Pod lifecycle operations into a singlePOST /v2/pods/{id}/actionendpoint plusPATCHfor in-place edits, and the request/response shape changes (nested create bodies, wrapped list responses, and RFC 9457 error objects). It calls out breaking specifics a v1 integrator will hit — the Serverless create body droppingtemplateId, the template and network-volume field renames, and a billing "false friend" where v1/billing/endpoints(Serverless) maps to v2/v2/billing/serverlesswhile v2/v2/billing/endpointsis a different resource (Public Endpoint billing).For net-new capabilities it highlights the catalog, Pod log streaming, Serverless worker/release observability, registry ECR delegations, and expanded billing endpoints.
Files touched:
api-reference-v2/migrate-from-v1.mdx(new)docs.json(one navigation entry added to the API v2 group)Trigger Events
Tip: Planning a big docs refactor? Use Deep Analysis to get help with the heavy lifting.