---
title: Runpod Migrate Skill for Claude Code
canonical: https://skillselion.com/skills/runpod/runpod-plugins-official/runpod-migrate
content_type: text/markdown
description: "runpod-migrate by runpod - A migration skill that moves a codebase from Runpod's GraphQL API or REST v1 to REST v2."
---

# Runpod Migrate Skill

Title: Runpod Migrate Skill for Claude Code

> runpod-migrate by runpod - A migration skill that moves a codebase from Runpod's GraphQL API or REST v1 to REST v2.

Canonical: https://skillselion.com/skills/runpod/runpod-plugins-official/runpod-migrate

A migration skill that moves a codebase from Runpod's GraphQL API or REST v1 to REST v2. It scans which code uses which version, rewrites the call sites, and reports breaking changes before verifying the result. A solo builder reaches for it when their GPU jobs run on the old Runpod API and they want the newer catalog and lifecycle states.

## Key facts

- Installs: 13,322
- GitHub stars: 50
- Author: runpod
- Repository: runpod/runpod-plugins-official
- Install command: `npx skills add https://github.com/runpod/runpod-plugins-official --skill runpod-migrate`
- Last updated: November 20, 2026

## What Runpod Migrate does

Moves a codebase from the Runpod GraphQL or REST v1 API to REST v2, inventorying call sites, rewriting them and flagging breaking changes.

Best for: Teams with existing code calling the Runpod API

Not for: Managing Runpod infrastructure directly

- Inventories which parts of the code use which Runpod API version
- Rewrites call sites and lists breaking changes
- Adds stock-aware GPU catalog lookups that v1 lacked

## SKILL.md

## Migrate to Runpod REST v2

Moves a codebase off the **GraphQL API** (`api.runpod.io/graphql`) and **REST v1**
(`rest.runpod.io/v1`) onto **REST v2** (`api.runpod.io/v2`).

**The payoff, in one line each**  -  you deliver these to the user at step 6, matched to
their actual code. Don't recite them now:

- **See stock before you rent**  -  `GET /v2/catalog/gpus?include=AVAILABILITY&product=POD`. v1 had no
  catalog at all, so every capacity retry loop was blind.
- **Endpoints return their own job URLs**  -  `requestUrls.run`, no more string-building.
- **Real lifecycle states**  -  `PROVISIONING`/`STARTING`/`ERROR` and an `actions` list, so
  wait-loops fail fast instead of timing out.
- **Mistakes fail loudly**  -  unknown request fields are rejected by name, with structured
  errors and honest status codes.

The full set, organized as *if their code does X → v2 offers Y*:
**[reference/unlocks.md](reference/unlocks.md)**  -  open it at step 6.

### Before you touch any code

**Infer the scope, state it, and move**  -  do not open with a questionnaire:

| The user says | Scope |
| --- | --- |
| "migrate to v2" / nothing specific | `all`  -  REST v1 **and** GraphQL |
| "just the REST stuff", "leave GraphQL alone" | `rest`  -  REST v1 only |
| "get us off GraphQL" | `graphql`  -  GraphQL only |

The table resolves every phrasing, so scope is not the thing to interrupt for. Say which
row you matched and carry on. **The question that does need asking comes later**  -  at
step 3, when the inventory shows the code depends on a capability v2 removed. That one
is a real fork and you cannot answer it for them.

Some things **have no v2 equivalent and must stay on GraphQL regardless of scope**:
account/billing identity (`myself`), secrets, spot/interruptible pods, cluster
create/delete. A "full" migration still leaves those calls in place  -  say so up front
rather than letting the user discover it at the end.

**Never rewrite the serverless job API.** `https://api.runpod.ai/v2/<endpointId>/run`,
`/runsync`, `/status`, `/stream`, `/cancel` is a *different API* that happens to have
`v2` in its path. It is unchanged and out of scope. The inventory reports it separately
so you do not touch it.

### The workflow

#### 1. Inventory  -  never migrate what you have not counted

The scanner ships **beside this file**, in the installed skill directory  -  not in the
user's repo. Resolve its path first; your working directory is their project:

```bash
# 1. Claude Code plugin installs expose the plugin root:
SCAN="$CLAUDE_PLUGIN_ROOT/skills/runpod-migrate/scripts/rp_api_inventory.py"
# 2. Otherwise substitute the directory you loaded this SKILL.md from  -  you know it:
[ -f "$SCAN" ] || SCAN="<directory containing this SKILL.md>/scripts/rp_api_inventory.py"
# 3. Last resort, search the usual install roots:
[ -f "$SCAN" ] || SCAN=$(find ~/.claude ~/.agents ~/.codex ~/.config -name rp_api_inventory.py 2>/dev/null | head -1)
python3 "$SCAN" --help >/dev/null || echo "scanner not found  -  resolve it before continuing"
```

Then, from the root of the user's repo:

```bash
python3 "$SCAN" . > runpod-api-inventory.md
python3 "$SCAN" . --json > runpod-api-inventory.json   # if you want to drive edits from it
python3 "$SCAN" . --scope rest                          # REST-only migrations
```

`runpod-api-inventory.md` lands in the user's repo  -  mention it, and remove it or
gitignore it before you hand the migration back.

Stdlib-only Python, no install. It reports every call site bucketed by generation  - 
GraphQL, REST v1, v1/GraphQL **field names**, REST v2 **already**, serverless job API,
SDK/CLI wrappers  -  plus a suggested file-by-file order.

**Show the user the inventory table before editing anything.** Users routinely do not
know what they are on: an agent picked a version for them months ago and wrote it down
nowhere. "3 files on v1, 2 on GraphQL, 1 already on v2, 2 on the job API  -  leave those
alone" is often the single most useful output of this whole skill.

##### What it detects, and what it cannot

It is regex line-scanning, but the classification is what makes it usable  -  plain
`grep -r runpod` gets two things actively wrong:

- **`api.runpod.ai/v2` vs `api.runpod.io/v2`.** One letter apart. `.ai` is the serverless
  job API and must not be touched; `.io` is the control plane you are migrating to.
  Grepping for `v2` tells you the codebase is "already migrated" when it is not.
- **Names legal in both versions.** `/pods` is a v1 path *and* a v2 path; `["pods"]` is
  v2 envelope-unwrapping; `idleTimeout` is top-level in v1 and nested under `workers` in
  v2. The scanner suppresses a hit when the same line carries v2 context, so it reports
  work that remains rather than every occurrence of a word.

It also looks for **field names, not just URLs**, which is what catches the files that
never spell "runpod": a module reading `p["costPerHr"]` off a wrapper's return value has
no URL, no import, no operation name  -  and is exactly what a v2 rename breaks silently.

Four things it genuinely cannot resolve. Check them by hand, every time:

| Blind spot | How to close it |
| --- | --- |
| **Base URL lives in config**, not code (`settings.yaml`, `.env`, a ConfigMap, Terraform) | The scanner does read those files, so the URL surfaces  -  but the *call sites* using it are elsewhere. Grep for whoever reads that config key. |
| **Paths assembled by a helper**  -  `_url("pods", pod_id, "stop")` | Reported under *possible indirect call sites*. Advisory, because `resp.json()["pods"]` looks identical. Open each one. |
| **SDK wrappers** (`import runpod`) | The API generation is a property of the installed *version*, not the code. Check `requirements.txt` / lockfile and the SDK's own release notes. |
| **Generated clients** | The OpenAPI/GraphQL document is the real source. Regenerate from the v2 spec instead of editing generated files. |

Then read the code the scanner flagged. It finds call sites; it does not understand your
wrappers. Trace who calls them  -  a renamed response field like `costPerHr → cost` breaks
every caller, not just the request builder. This is the one step where a code-graph or
LSP index earns its keep, if one is already available.

#### 2. Brief the breaking changes  -  before the diff, not after

Read **[reference/breaking-changes.md](reference/breaking-changes.md)** and tell the
user which ones actually apply to *their* code. Two classes, and the second is the one
they are afraid of:

1. **Renames and moves**  -  loud. v2 rejects unknown request fields with `422` listing
   them by name, so a missed rename cannot slip into production silently.
2. **Same name, different meaning**  -  quiet, and the reason a green test suite is not
   proof. The reference enumerates every one of them; the two that bite hardest:
   `flashboot` went from boolean to a three-value enum, and v1's `/billing/endpoints`
   (serverless spend) is v2's `/billing/serverless`  -  v2's `/billing/endpoints` bills a
   *different product* (public endpoints) and answers `200` with a correct total for
   that product, which is not the one the caller asked for.

#### 3. Plan, split into required vs cleanup

Write the plan down before editing, and keep these buckets separate all the way through
to the final summary:

- **Required**  -  it does not work on v2 without this.
- **Cleanup**  -  it works either way, but v2 lets you delete code (hand-built job URLs,
  hand-rolled availability retry, polling loops that can now be SSE).
- **Decisions the user must make**  -  the code depends on something v2 removed outright:
  spot/interruptible pods, savings plans, `dockerEntrypoint`, placement constraints
  (`countryCodes`, `minRAMPerGPU`, …), pod `reset`, per-pod GPU fallback. See
  [breaking-changes.md](reference/breaking-changes.md) Class 3  -  and check it rather
  than working from memory, because things leave this bucket as v2 grows. CUDA pinning,
  `templateId` and CPU endpoint writes all used to be here and are not any more.

**Stop and ask before writing code in that third bucket**  -  but bring the replacement
with you. Some of these have a working rebuild and some genuinely have nothing, and the
difference decides what you are asking. Where a rebuild exists (`countryCodes` →
[catalog filter + `dataCenterIds` + a placement
assert](reference/breaking-changes.md#replacing-countrycodes-and-the-rest-of-the-placement-constraints),
per-pod GPU fallback → [an availability-ordered
loop](reference/breaking-changes.md#replacing-the-gpu-fallback-list-pods-only)), show it
and ask the one question that changes it  -  for `countryCodes`, whether the restriction
was a preference or a compliance requirement. Where nothing exists, the options are
accept the behavior change, keep that call on v1/GraphQL, or redesign around it, and only
the user can pick.

Either way, do not present a removal as a dead end when a rebuild exists  -  that pushes
the user into keeping a v1 call they did not need to keep. And never drop the field with
a `# no v2 equivalent` comment: that is the failure mode this bucket exists to prevent,
because it silently changes what their infrastructure does. If the bucket is empty, say
so  -  that is reassuring and takes one line.

#### 4. Migrate, one file per commit

Work in the scanner's suggested order (fewest call sites first)  -  **with one override:
if several call sites share a transport helper, migrate the helper first**, whatever its
count. The scanner orders by call-site count and cannot see imports, so it will happily
put a consumer ahead of the module it imports its client from. Migrating a consumer
first means writing against an interface you are about to change.

Per file:

- Map paths and fields with **[reference/rest-v1-to-v2.md](reference/rest-v1-to-v2.md)**
  or **[reference/graphql-to-v2.md](reference/graphql-to-v2.md)**. If a field isn't in
  the tables, or the API disagrees with them, check the spec directly  - 
  [Ground truth](#ground-truth-check-the-spec-yourself).
- **`gpuTypeIds` + `gpuTypePriority` on a *pod* means you are writing new code, not
  renaming fields.** A v2 pod takes one GPU type, so the server-side fallback becomes a
  client-side loop over the catalog. Working implementation:
  [breaking-changes.md → Replacing the GPU fallback list](reference/breaking-changes.md#replacing-the-gpu-fallback-list-pods-only).
  **Endpoints need no loop**  -  `gpu.pools` is already a list and workers land on
  whichever listed pool has capacity.
- **Always request availability on catalog reads  -  with `product`.** Any
  `GET /v2/catalog/gpus`, `/catalog/cpus`, or `/catalog/datacenters` this migration
  introduces gets `include=AVAILABILITY` (`GPU_AVAILABILITY`/`CPU_AVAILABILITY` for
  datacenters). Availability is the top-of-mind question for every Runpod user and the
  call costs the same. Do not omit it because the current code did not ask for it  -  v1
  could not.

  **`include=AVAILABILITY` alone is a `400`.** On `/catalog/gpus` and `/catalog/cpus`,
  `product` is required with it and invalid without it  -  `400` either way. There is no
  default, deliberately: the same GPU can be scarce for `POD` and plentiful for
  `SERVERLESS`, so the context has to be stated. Pick the one matching what you are
  creating (`POD`, `SERVERLESS`, or `CLUSTER`; CPUs take `POD` or `SERVERLESS`):

  ```
  GET /v2/catalog/gpus?include=AVAILABILITY&product=POD
  ```
- Offer the **rollback flag** (`RUNPOD_API_V1=1`) while v2 is new to them:
  **[reference/rollback-flag.md](reference/rollback-flag.md)**. Worth it for a service
  in production; skip it for a one-off script.
- **Never change behavior and API version in the same commit**  -  including the
  improvements v2 makes possible. Failing fast on `status == "ERROR"` instead of timing
  out is a genuine win and it belongs in the *next* commit; folding it into the
  migration commit means a rollback has to give up both. Land those in the **cleanup**
  bucket, separately.

A full before/after of a real client  -  pod create with GPU fallback, endpoint create
with the container config inlined, GraphQL dashboard  -  is in
**[reference/worked-example.md](reference/worked-example.md)**.

#### 5. Verify against the live API

Static review is not enough; v2's validator is strict and its errors are precise.
Re-run the scanner to prove the call sites are gone, then exercise the real paths:

```bash
python3 "$SCAN" . --scope rest --fail-on-legacy   # exit 1 if v1 remains
```

Two markers, and they mean different things  -  do not reach for the wrong one:

| Marker | Use it for |
| --- | --- |
| `rp-migrate: keep-v1` | legacy code kept **on purpose**  -  a `RUNPOD_API_V1` rollback branch, or a GraphQL call with no v2 equivalent. Reported under *kept on purpose*. |
| `rp-migrate: ignore` | a **false positive** on code that is already correct. Says "this isn't legacy", not "this is legacy I'm keeping". Reported under *marked false positives*. |

Both accept `line`, `start`/`end` region, or `file` scope, and both drop out of the plan
and out of `--fail-on-legacy`. Using `keep-v1` to silence a false positive records a lie
in the report  -  reach for `ignore` there.

**Where the gate can still be wrong.** The same blind spots from step 1 invert after a
migration: before, they hide v1 code; after, they can flag correct v2 code. The scanner
handles the two common cases  -  trailing `# was imageName` annotations, and a base URL
held in a constant (`f"{BASE}/pods"` where `BASE` is a v2 URL defined anywhere in the
file). Beyond those  -  a base URL imported from another module, or built at runtime from
config  -  it can still misread correct code as legacy. Read the flagged lines before
believing the exit code, and mark true false positives with `ignore` rather than
weakening the gate.

- **Reads** are free  -  list pods, endpoints, volumes, catalog. Confirm you unwrap the
  new envelope (`{"pods": [...]}`, not a bare array).
- **Writes** cost money. Create → assert → delete, on the smallest thing that proves the
  shape. Never test against resources the user already has.
- Decode `422`s with the table in
  [reference/breaking-changes.md](reference/breaking-changes.md#reading-a-422)  -  including
  the confusing one where a *missing required field* makes the validator report your
  *valid* fields as "additional properties not allowed".

#### 6. Summarize  -  this is the artifact they will actually read

Most users read the summary and not the diff. Structure it exactly like this:

```
## Required for the migration
<file:line>  -  what changed and why it had to

## Cleanup enabled by v2
<file:line>  -  what got deleted or simplified

## Behavior changes to watch
the same-name-different-meaning items that applied

## Still on GraphQL (no v2 equivalent)
myself / secrets / spot pods / clusters  -  and why

## Unlocks: what you can build now
tied to what this codebase already does
```

That last section is the highest-value part. Do not paste a generic feature list  - 
look at what this user has been building and struggling with, including anything you
already know from the session, and name where v2 changes it. "Your `wait_until_running`
loop times out on failed pods; v2's `ERROR` status lets it fail in seconds" beats "v2 has
richer status values". [reference/unlocks.md](reference/unlocks.md) is organized as
*if the code does X → v2 offers Y* for exactly this.

### Ground truth: check the spec yourself

The mapping tables in `reference/` were verified against the live API on **2026-08-10**.
v2 is actively developed, so treat them as a fast path, not as the authority. Both specs
are public and need no auth:

```bash
curl -s https://api.runpod.io/v2/openapi.json  -o /tmp/rp-v2.json
curl -s https://rest.runpod.io/v1/openapi.json -o /tmp/rp-v1.json
```

**What a request body actually accepts, and what is required** (`*`). Worth running
before writing any create call  -  it resolves `allOf` composition, which a naive read of
the raw JSON misses:

```bash
python3 - CreateEndpointRequest <<'PY'
import json, sys

Excerpt. The rest of the file is on the canonical page and in the source repository.

## Runpod Migrate FAQ

### Is Runpod Migrate safe to install?

skills.sh reports 2 of 3 security scanners passed. Review the Security Audits panel on this page before installing in production.

## Machine access

- [Sitemap](https://skillselion.com/sitemap.xml)
- [llms.txt](https://skillselion.com/llms.txt)
- [llms-full.txt](https://skillselion.com/llms-full.txt)
- [Developer resources](https://skillselion.com/developers)
- [OpenAPI spec](https://skillselion.com/openapi.json)
- [MCP handshake](https://skillselion.com/.well-known/mcp)
- [API catalog](https://skillselion.com/.well-known/api-catalog)
- [AI catalog](https://skillselion.com/.well-known/ai-catalog.json)
- [Pricing](https://skillselion.com/pricing.md)
- [Auth](https://skillselion.com/auth.md)
- [AGENTS.md](https://skillselion.com/AGENTS.md)
- [Contact](https://skillselion.com/contact)
- [Home](https://skillselion.com/)
