diff --git a/api-reference-v2/migrate-from-v1.mdx b/api-reference-v2/migrate-from-v1.mdx new file mode 100644 index 000000000..a98ca9a02 --- /dev/null +++ b/api-reference-v2/migrate-from-v1.mdx @@ -0,0 +1,166 @@ +--- +title: "Migrate from API v1" +sidebarTitle: "Migrate from v1" +description: "Move your integrations from the Runpod REST API v1 to the v2 base URL, endpoints, and request and response shapes." +--- + +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. + +Read this guide if you have an existing integration built against the v1 API. REST API v1 is deprecated and will be retired on December 1, 2026. Migrate your integrations to v2 before that date. + +## 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](/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. + +## 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. + +| Resource | v1 path | v2 path | +| --- | --- | --- | +| Pods | `/pods` | `/v2/pods` | +| Serverless | `/endpoints` | `/v2/serverless` | +| Templates | `/templates` | `/v2/templates` | +| Network volumes | `/networkvolumes` | `/v2/network-volumes` | +| Registries | `/containerregistryauth` | `/v2/registries` | +| Instant Clusters | No equivalent | `/v2/clusters` | +| Pod billing | `/billing/pods` | `/v2/billing/pods` | +| Serverless billing | `/billing/endpoints` | `/v2/billing/serverless` | +| Network volume billing | `/billing/networkvolumes` | `/v2/billing/network-volumes` | + +v2 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. + + + 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. + + +## 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). + + + The v1 `reset` operation has no v2 action equivalent. The v2 action enum is limited to `start`, `stop`, `restart`, and `terminate`. + + +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}`. + +The following example shows how stopping a Pod changes between versions. + + + +```bash v1 +curl --request POST \ + --url https://rest.runpod.io/v1/pods/{podId}/stop \ + --header 'Authorization: Bearer RUNPOD_API_KEY' +``` + +```bash v2 +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"}' +``` + + + +Instead of targeting a dedicated `/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 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. + +- 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](/api-reference-v2/serverless/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](/api-reference-v2/templates/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](/api-reference-v2/network-volumes/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. + + + +```json v1 +[ + { "id": "pod-1" }, + { "id": "pod-2" } +] +``` + +```json v2 +{ + "pods": [ + { "id": "pod-1" }, + { "id": "pod-2" } + ] +} +``` + + + +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. + +### 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. + + + +```json v1 +{ + "message": "Pod not found" +} +``` + +```json v2 +{ + "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](/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). + +- 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. + +- 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). + +## Next steps + + + + Review the v2 base URL, authentication, and available resources. + + + See the nested v2 request schema for provisioning a Pod. + + + Query your Serverless endpoints with the wrapped v2 response. + + + Browse available GPU types with the new catalog endpoints. + + diff --git a/api-reference-v2/overview.mdx b/api-reference-v2/overview.mdx index 4ab319ccb..cc0bbcd6b 100644 --- a/api-reference-v2/overview.mdx +++ b/api-reference-v2/overview.mdx @@ -3,11 +3,6 @@ title: "API v2" sidebarTitle: "Overview" description: "Programmatically manage Runpod resources using the API v2." --- - - - The REST API v2 is currently in beta. Endpoints and behavior may change before general availability. - - The Runpod REST API v2 provides programmatic access to your Runpod resources over standard HTTP. Use it to create and manage Pods, query Serverless endpoints, provision storage, and retrieve billing data — without using the console. ## Base URL diff --git a/api-reference/overview.mdx b/api-reference/overview.mdx index 6c15fc982..ac7e34017 100644 --- a/api-reference/overview.mdx +++ b/api-reference/overview.mdx @@ -1,13 +1,14 @@ --- title: "Overview" +sidebarTitle: "Overview" description: "Use the Runpod API to programmatically manage your compute resources. Review authentication, request formats, and response details for the Runpod API." --- The Runpod REST API v1 provides programmatic access to all Runpod compute resources. Integrate GPU infrastructure into your applications, workflows, and automation systems. - -REST API v1 is in maintenance mode and is no longer being actively developed. For new integrations, use [REST API v2](/api-reference-v2/overview). - + +REST API v1 is deprecated and will be retired on **December 1, 2026**. Migrate your integrations to REST API v2 before that date. See the [migration guide](/api-reference-v2/migrate-from-v1) to get started. + ## Available resources diff --git a/docs.json b/docs.json index dc14a2ca9..050bfa5a5 100644 --- a/docs.json +++ b/docs.json @@ -455,7 +455,9 @@ "groups": [ { "group": "API v1", - "pages": [] + "pages": [ + "api-reference/overview" + ] }, { "group": "Pods", @@ -495,8 +497,7 @@ ] }, { - "group": "Templates", - "root": "api-reference/overview", + "group": "Templates", "pages": [ "api-reference/templates/POST/templates", "api-reference/templates/GET/templates", @@ -526,12 +527,13 @@ ] }, { - "tab": "API v2 (BETA)", + "tab": "API v2", "groups": [ { "group": "API v2", "pages": [ - "api-reference-v2/overview" + "api-reference-v2/overview", + "api-reference-v2/migrate-from-v1" ] }, { diff --git a/sdks/graphql/configurations.mdx b/sdks/graphql/configurations.mdx index 33b8f0b2e..5f10a307d 100644 --- a/sdks/graphql/configurations.mdx +++ b/sdks/graphql/configurations.mdx @@ -8,6 +8,10 @@ Use the GraphQL API to manage Pods, templates, and Serverless endpoints through All requests go to `https://api.runpod.io/graphql` with your API key included as a query parameter. For the complete schema including all available queries, mutations, fields, and inputs, see the [GraphQL Spec](https://graphql-spec.runpod.io/). + +The GraphQL API is deprecated and will be retired in early 2027. For new integrations, use [REST API v2](/api-reference-v2/overview). + + ## Quick start Make a request using cURL: