[justinwlin]

REST v1 (rest.runpod.io/v1) is retired on 2026-11-15, but five guide pages still show v1 curl examples. The endpoint settings page also states console defaults without saying so, and several differ from REST v2.

What changes

• v1 → v2 examples in pods/manage-pods.mdx (create, create from template, stop, start, update, delete), pods/templates/manage-templates.mdx, serverless/endpoints/overview.mdx, storage/network-volumes.mdx and tutorials/pods/comfyui.mdx.

  • Every route and field is checked against api-reference-v2/openapi.json. For example: gpu: {id, count}, disk, mounts.persistent, dataCenter, POST /v2/pods/{id}/action with {"action":"stop"}, and type, gpu.pools, workers, scaling for endpoints.
  • Links now go to the matching api-reference-v2 pages.
  • Two v1 behaviors have no exact v2 equivalent, and the text says so:
    • templates have no readme field;
    • endpoints select GPU pools, not GPU types (ADA_24 holds the RTX 4090), with gpu.excludedTypes to narrow a pool.

• serverless/endpoints/endpoint-configurations.mdx: the table is labeled as console defaults. The REST v2 defaults are added where they differ:

  • idle timeout: 5 s in the console, workers.idleTimeout 10 s in REST v2;
  • execution timeout: 600 s in the console, timeout 300000 ms in REST v2;
  • FlashBoot: on in the console, flashboot OFF in REST v2;
  • Job TTL has no endpoint-level field in REST v2.

• Links: integrations/overview.mdx and pods/templates/create-custom-template.mdx now link to the v2 create-endpoint and create-template references. integrations/overview.mdx also links its Pod connection details to Get a Pod; serverless/sdks.mdx, get-started/mcp-servers.mdx, and the REST API card in get-started/connect-to-runpod.mdx link to the v2 overview instead of the v1 OpenAPI page.

• Navigation: the API v2 tab now comes before API v1 in docs.json. Nothing else in the file changes.

• tests/scripts/cleanup.py: calls REST v2 so it keeps working after v1 is retired. Endpoints move from /v1/endpoints to /v2/serverless, list calls follow cursor pagination (pagination.nextCursor), and deletes accept 204, which v2 returns on success. The v1 version checked for 200, so it would have reported every v2 delete as a failure.

• Pod start note: pods/manage-pods.mdx now explains that, unlike the console, the REST start action does not offer a zero-GPU start and returns 400 if its host GPUs are no longer free.

Not changed

integrations/transformer-lab.mdx still tells users to configure https://rest.runpod.io/v1 as Transformer Lab's base URL. That's correct for now. Transformer Lab's provider (api/transformerlab/compute_providers/runpod.py in transformerlab/transformerlab-app) defaults to that URL and sends v1 request fields: imageName, gpuTypeIds, gpuCount and containerDiskInGb on POST /pods. Pointing it at v2 would break pod creation, and it will stop working when v1 is retired on 2026-11-15 unless Transformer Lab moves to v2. That needs to be raised with Transformer Lab. This page should change once they ship v2 support.

Verification

• Rebased onto main on 2026-10-26. The idle timeout paragraph keeps main's worker-lifecycle wording (afc1b36) and adds the REST v2 default.

• All 10 curl examples validated with jsonschema against the current api-reference-v2/openapi.json (v2.0.0): every route and method exists, every body passes its full request schema (required fields, enums, nested objects), and no body has fields the schema doesn't define.

• Live GET /v2/catalog/gpus and /v2/catalog/datacenters: NVIDIA GeForce RTX 4090 is a valid gpu.id, its pool is ADA_24, and US-KS-2 is a valid data center.

• REST v2 defaults cited match the spec: workers.idleTimeout 10, timeout 300000, flashboot OFF, and CreateEndpointRequest has no TTL field and requires name, type and scaling. Templates have no readme field.

• Console defaults in the table match main-ui console/src/features/Serverless/New/defaults.ts: active workers 0, max workers 3, 1 GPU, idle timeout 5 s, execution timeout 600 s, FlashBoot on.

• Live run (2026-10-26): every example was sent to the production v2 API with the body read straight from the page (only names and placeholder IDs swapped):

  Example	Result
  Create a template (manage-templates.mdx)	201
  Create a Pod (manage-pods.mdx)	201
  Create a Pod from a template	201
  Stop a Pod (action: stop)	200
  Start a Pod (action: start)	400, host had no free GPUs (now documented)
  Update a Pod (disk, mounts.persistent)	200
  Create a ComfyUI Pod (comfyui.mdx)	201
  Create a Serverless endpoint (overview.mdx)	201
  Create a network volume (network-volumes.mdx)	201
  Delete Pod, endpoint, network volume, template via cleanup.py delete functions	all succeeded (204)

  The first attempt hit "no longer any instances available" for the RTX 4090 on all three Pod creates. The same bodies succeeded minutes later, so that was capacity, not the request. Everything the run created was deleted by ID.

• cleanup.py: the four list functions also ran live and return every resource with its ID.

• docs.json: parsed both versions and confirmed they differ only in tab order.

• mintlify broken-links: none. Vale isn't installed locally.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
runpod-docs	🟢 Ready	View Preview	Oct 30, 2026, 4:04 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

[OneAsterisk]

Claude review, round 1

Verdict: Approved — the ten curl bodies, the cited REST v2 defaults, the link targets, the docs.json reorder, and the cleanup.py v2 port all check out against api-reference-v2/openapi.json; what remains is one wrong rationale in the PR body and a handful of wording and robustness fixes.
Approval gate: 0 Critical, 0 High, 8 Medium+Low → approved.

Existing feedback

• mintlify[bot]: preview-deployment link only, no claims to verify.

PR description vs code

Claim	Status	Where
v1 → v2 curl examples on the five guide pages; no v1 URLs or field names remain	✅	10 blocks; grep for rest.runpod.io/v1 and v1 field names in the nine pages is empty
Every route and field checked against the spec (gpu.{id,count}, disk, mounts.persistent, dataCenter, action, type, gpu.pools, workers, scaling)	✅	All fields resolve in CreatePodRequest, UpdatePodRequest, CreateTemplateRequest, CreateEndpointRequest, CreateNetworkVolumeRequest; enums and minimums satisfied
REST v2 defaults: workers.idleTimeout 10 s, timeout 300000 ms, flashboot OFF; name/type/scaling required; no TTL field; no template readme	✅	Spec defaults and required lists match; Endpoint.timeout is described as "per-request execution timeout in milliseconds"
ADA_24 holds the RTX 4090; gpu.excludedTypes narrows a pool	✅ (spec)	GpuType.pool example ADA_24; excludedTypes description. Live membership not checked
Links go to matching api-reference-v2 pages; mintlify broken-links clean	✅	All 7 new hrefs exist as files and in docs.json
docs.json: only the tab order changes	✅	Every changed line appears once removed and once added; the rest of the file is byte-identical
cleanup.py: /v2/serverless, cursor pagination, 204 on delete	✅	limit max is 1000, pagination.{hasNextPage,nextCursor} and the four wrapper keys match; all four DELETE routes list only 204
Pod start returns 400 "not enough free GPUs"	⚠️	400 is listed for the action route with no description; 409 is the documented status-mismatch code. Live observation, not spec
Not changed: v2 Pod has no public IP or port-mapping fields	❌	GET /v2/pods/{id} returns runtime.ports[] = {private, public, type, ip} ("Live port mapping for a running pod") and ssh.direct {host, port}. See Medium below
Spec validated is "v2.13.0"	⚠️	api-reference-v2/openapi.json at head has info.version 2.0.0
Transformer Lab still on v1; rebase; console defaults from main-ui; live run	—	External or not reproducible read-only

Findings

Medium

• integrations/overview.mdx:51 still links the v1 GET /pods/{podId} reference, and the reason given for keeping it is wrong. The v2 single-Pod response carries the live mapping in runtime.ports[].ip and runtime.ports[].public (null on the list route, so the single-pod page is the right target), plus ssh.direct.host/port for SSH. Point the sentence at /api-reference-v2/pods/get-a-pod and name those fields, and fix the "Not changed" paragraph in the PR body. Filed as a file-level comment because the line is outside the diff.

Low

• pods/manage-pods.mdx:172 — the section intro at line 144 says you may get a zero-GPU Pod (the console option described in pods/troubleshooting/zero-gpus.mdx:17); the new REST sentence says the request fails. Scope it ("unlike the console…") and paraphrase the error instead of quoting backend copy the spec does not define. Inline.
• serverless/endpoints/overview.mdx:86 — the Tip directly under the tabs still says "specify multiple GPU types in priority order", right after the new paragraph says REST v2 selects pools, not GPU types, and the spec describes pools as "whichever listed pool has capacity" with no priority order. Scope the Tip to the console and mention listing several gpu.pools for REST.
• serverless/endpoints/endpoint-configurations.mdx:18 — the intro lists idle timeout, execution timeout, and FlashBoot as REST differences but not Job TTL, while the table two lines down shows 24h; the correction is 88 lines later. Inline with suggestion.
• serverless/endpoints/endpoint-configurations.mdx:128 — states the REST default is OFF but not how to turn it on (FLASHBOOT); readers will guess true. Inline with suggestion.
• serverless/sdks.mdx:129 and get-started/mcp-servers.mdx:15 — "API reference" and "Runpod REST API" still link /api-reference/overview (v1), the same kind of card the PR repointed in connect-to-runpod.mdx. Repoint to /api-reference-v2/overview, or state that the MCP server targets v1 if that is the case.
• tests/scripts/cleanup.py:50 and :83 — no timeout= on the requests calls; tests/scripts/README.md documents running this in GitHub Actions, where a stalled connection hangs the job. Both lines are new. Inline.
• tests/scripts/cleanup.py:84 — the failure path drops the status and problem detail, so CI prints "Failed to delete" with no reason (Pods can return 409). The spec lists only 204 for success, so 200 is dead. Inline.

Nits

• serverless/endpoints/endpoint-configurations.mdx:106 — CreateEndpointRequest is an OpenAPI component name the rendered reference never shows; say "when you create an endpoint through REST v2" and link the page. Inline.
• pods/templates/manage-templates.mdx:81-82 — "entrypoint": [] and "cmd": [] are no-op carryovers from v1 dockerEntrypoint/dockerStartCmd; the page's own Note at line 32 says to leave the start command blank. Inline suggestion deletes them.
• pods/templates/manage-templates.mdx:98 — "keep setup instructions outside the template request" is vague; say where (for example the image's repository README).
• PR body: cite the spec version that is actually in the repo (2.0.0) or say where v2.13.0 came from.

Simplification opportunities

1. tests/scripts/cleanup.py — eight one-line wrappers (list_*, delete_*) each have exactly one call site, and main() repeats the same 17-line block four times. A table of (label, path, key, counter) driving list_resources/delete_resource directly removes about 85 lines. The wrappers were shaped by this PR; the main() duplication is pre-existing, so a follow-up is fine.

Verified clean

• All 10 curl bodies: every field exists in the resolved request schema, nesting is right, category: "NVIDIA", type: "QUEUE", scaling.type: "QUEUE_DELAY" are valid enum members, mounts.persistent.size meets the minimum of 10, queueDelay 4 ≥ 0.5.
• Base URL https://api.runpod.io/v2 matches servers[0].url; --header "Authorization: Bearer $RUNPOD_API_KEY" matches the form used by 54 other guide pages.
• Link text uses sentence case per .claude/style-guide.md; no e.g./i.e. in added lines; "Runpod" spelled correctly.
• cleanup.py: main() is byte-identical to the version on main; (i.get("name") or "") handles missing and null names; list[dict[...]] generics were already in the baseline and stats.py uses dict | None, so no new Python requirement.
• Both CI checks pass; tests/scripts/README.md, .claude/testing.md, and tests/TESTS.md never name the API version, so nothing there went stale.

Out of scope, worth a follow-up

• docs.json redirects at lines 1207, 1291, 1315, 1391, 1651, 1887, and 1951 still land on v1 reference pages (v2 equivalents exist, including api-reference-v2/billing/get-pod-billing-history.mdx). The PR body promises no other docs.json changes, so not for this PR.
• tests/TESTS.md cleanup rules list clusters; cleanup.py has never handled them and GET /v2/pods defaults includeClusterPods=false. v2 now has GET/DELETE /v2/clusters.

Questions for the author

• cleanup.py:41 adds a User-Agent: runpod-docs-cleanup/1.0 header that the PR body does not mention. Does v2 reject the default python-requests agent, or is this for attribution? Either way, one line in the body would help.
• Is the Runpod API MCP server (get-started/mcp-servers.mdx) backed by v1 or v2? That decides the wording of that link.

---

_{Reviewed by Claude (claude-fable-5-1) via the pr-review skill. Tokens: 1,588 in / 50,274 out / 5,111,811 cache read / 425,984 cache write = 5,589,657 (main session plus two sub-agents, as of posting). Estimated cost: $12.33 at $10 in, $50 out, $0.25 cache read, $20 cache write per MTok (1-hour cache TTL, writes at 2× input). Round 1 of this PR. This is automated assistance; a human owns the final call.}

[OneAsterisk]

Claude review, round 2

Verdict: Approved — every round 1 finding, nit, and PR-body correction is addressed at 9215dceb, and the follow-up commit adds nothing beyond two nits.
Approval gate: 0 Critical, 0 High, 0 Medium+Low → approved.

GitHub dismissed the round 1 approval when the follow-up commit was pushed (timeline review_dismissed, no message). This round re-approves. The branch was then rebased onto main (7a06795) while I was reading; the PR diff at 9215dceb is byte-identical to the pre-rebase diff apart from hunk offsets, so this round covers 9215dceb.

Status of prior findings

#	Finding	Severity	Status	Evidence
R1-1	integrations/overview.mdx linked the v1 GET /pods/{podId} page; PR body gave a wrong reason	Medium	Fixed	integrations/overview.mdx:51 names runtime.ports[].ip / runtime.ports[].public and links /api-reference-v2/pods/get-a-pod; the "Not changed" section now covers only Transformer Lab
R1-2	REST start note contradicted the zero-GPU intro and quoted backend copy	Low	Fixed	pods/manage-pods.mdx:173
R1-3	Tip said "GPU types in priority order" under the pools paragraph	Low	Fixed	serverless/endpoints/overview.mdx:86; matches the spec's "whichever listed pool has capacity"
R1-4	Quick-reference intro omitted job TTL	Low	Fixed	serverless/endpoints/endpoint-configurations.mdx:18
R1-5	FlashBoot default stated without the enabling value	Low	Fixed	serverless/endpoints/endpoint-configurations.mdx:128
R1-6	serverless/sdks.mdx and get-started/mcp-servers.mdx still linked v1	Low	Fixed	Both now /api-reference-v2/overview. The MCP server's REST base defaults to https://api.runpod.io (runpod-mcp src/_shared/hosts.ts:17), the v2 host, so v2 is the right target
R1-7	No timeout= on the requests calls	Low	Fixed	tests/scripts/cleanup.py:51, :86
R1-8	Dead 200 branch; failure path dropped the reason	Low	Fixed	tests/scripts/cleanup.py:88-94 returns (bool, str), treats only 204 as success, reads detail (the field in the spec's ErrorResponse); main() prints it
R1-9	CreateEndpointRequest component name in prose	Nit	Fixed	endpoint-configurations.mdx:106
R1-10	No-op entrypoint: [] / cmd: []	Nit	Fixed	Removed; the body still parses as JSON with 9 keys
R1-11	"outside the template request" was vague	Nit	Fixed	pods/templates/manage-templates.mdx:96
R1-12	PR body cited spec v2.13.0	Nit	Fixed	Body now says v2.0.0

Existing feedback

• mintlify[bot]: preview-deployment link only, refreshed for 9215dceb.
• My eight round 1 threads: replied "Verified fixed" and resolved.

PR description vs code

Claim	Status	Where
Pod start note: no zero-GPU start via REST, 400 when host GPUs are gone	✅	pods/manage-pods.mdx:173
"Not changed" covers Transformer Lab only	✅	The port-mapping claim is gone
Spec validated is v2.0.0	✅	api-reference-v2/openapi.json info.version
Links: integrations/overview.mdx, create-custom-template.mdx, connect-to-runpod.mdx	⚠️	True, but the bullet omits the three repoints added in 9215dceb: integrations/overview.mdx (Get a Pod), serverless/sdks.mdx:129, get-started/mcp-servers.mdx:15. See Nits
cleanup.py deletes accept 204	✅	cleanup.py:88; all four DELETE routes list only 204 for success
Everything else	✅	Unchanged since round 1; the round 1 table still holds

Findings

Critical

None.

High

None.

Medium

None.

Low

None.

Nits

• serverless/endpoints/endpoint-configurations.mdx:106 — "in the job policy" has no link; the policy.ttl object is documented at serverless/endpoints/send-requests.mdx:99-118. Inline suggestion.
• PR body, "Links" bullet — list the three repoints from 9215dceb so the body names every link change.

Simplification opportunities

1. tests/scripts/cleanup.py — same as round 1: the four blocks in main() are now 18 lines each and differ only by label, path, key, and counter. A (label, path, key, counter) table driving list_resources / delete_resource removes about 85 lines. Pre-existing shape; follow-up PR.

Verified clean

• Diff since round 1 (3c624866...9215dceb): 8 files, +39/−27, read in full. Every hunk maps to a round 1 finding; nothing else changed.
• All five v2 link targets touched in this round exist as files and in docs.json: pods/get-a-pod, serverless/create-a-serverless-endpoint, overview, templates/create-a-template, catalog/list-gpu-types.
• No /api-reference/ (v1) link remains in any of the 12 changed .mdx pages.
• Spec: PodRuntimePort has ip and public (both nullable) and Pod references PodRuntime and PodSsh; BaseEndpointGpuConfig.pools says "whichever listed pool has capacity"; ErrorResponse has detail.
• Template curl body still parses as JSON after removing entrypoint / cmd; no field was added.
• docs.json is byte-identical to round 1.
• Both CI checks pass at 9215dceb (tooltip imports, Mintlify deployment).
• cleanup.py: except ValueError catches requests.exceptions.JSONDecodeError (a ValueError subclass), so an HTML error page falls back to resp.text; tuple[bool, str] needs no newer Python than the existing list[dict[str, Any]].

Questions for the author

• Carried from round 1: cleanup.py:41 sends User-Agent: runpod-docs-cleanup/1.0. Required by v2, or attribution? One line in the PR body would settle it.

---

_{Reviewed by Claude (claude-fable-5-1) via the pr-review skill. Tokens: 516 in / 34,039 out / 1,818,377 cache read / 150,963 cache write = 2,003,895 (main session, no sub-agents, as of posting). Estimated cost: $5.18 at $10 in, $50 out, $0.25 cache read, $20 cache write per MTok (1-hour cache TTL, writes at 2× input). Round 2 of this PR. This is automated assistance; a human owns the final call.}

[OneAsterisk]

Claude review, round 3

Verdict: Approved — the only change since round 2 is the one-line link fix round 2 asked for, and nothing else in the PR moved.
Approval gate: 0 Critical, 0 High, 0 Medium+Low → approved.

Round 2's approval was dismissed automatically when d4e4b475 was pushed (timeline review_dismissed, no message, same as round 1). This round re-approves.

Status of prior findings

#	Finding	Severity	Status	Evidence
R2-1	"in the job policy" had no link	Nit	Fixed	serverless/endpoints/endpoint-configurations.mdx:106 links /serverless/endpoints/send-requests#execution-policies. The heading is at send-requests.mdx:99, and lines 98 and 112 of the same page already use that anchor. Thread resolved by the author; replied to confirm.
R2-2	PR body "Links" bullet omitted three repoints	Nit	Fixed	Body now names serverless/sdks.mdx, get-started/mcp-servers.mdx, and the Get a Pod link in integrations/overview.mdx
R1-1 to R1-12	All twelve round 1 findings	Medium/Low/Nit	Fixed (round 2)	Unchanged since 9215dceb; the diff since round 2 touches only line 106 of endpoint-configurations.mdx

Existing feedback

• mintlify[bot]: preview-deployment link only, refreshed for d4e4b475 at 16:04 UTC.
• @justinwlin resolved my round 2 thread after pushing the fix. Verified at head and replied in the thread.

PR description vs code

Claim	Status	Where
Job TTL has no endpoint-level field in REST v2	✅	endpoint-configurations.mdx:106, now linking the per-request policy.ttl docs
"Links" bullet lists every repointed link	✅	Body matches the diff: integrations/overview.mdx (two links), create-custom-template.mdx, sdks.mdx, mcp-servers.mdx, connect-to-runpod.mdx
Everything else	✅	Unchanged since round 2; the round 1 and round 2 tables still hold

Findings

Critical

None.

High

None.

Medium

None.

Low

None.

Nits

• serverless/endpoints/endpoint-configurations.mdx:106 and :112 now both send the reader to the same anchor for per-request ttl, six lines apart. Line 112 is pre-existing; folding the REST v2 note into it (or dropping 112) would leave one instruction. Optional, non-blocking.

Simplification opportunities

1. tests/scripts/cleanup.py — unchanged from rounds 1 and 2: a (label, path, key, counter) table driving the four main() blocks removes about 85 lines. Pre-existing shape; follow-up PR.

Verified clean

• Diff since round 2 (9215dceb..d4e4b475): 1 file, +1/−1, read in full. The only change is the added link.
• Link target: send-requests.mdx:99 is ### Execution policies, which Mintlify slugs to #execution-policies; the page already links that anchor from lines 98 and 112.
• Both CI checks pass at d4e4b475 (tooltip imports, Mintlify deployment).
• No /api-reference/ (v1) link or rest.runpod.io/v1 host remains in any of the 11 changed .mdx pages. The Transformer Lab page the body leaves alone is not in this diff.
• docs.json and the other 11 changed files are byte-identical to round 2.

Questions for the author

• Carried from rounds 1 and 2: tests/scripts/cleanup.py:41 sends User-Agent: runpod-docs-cleanup/1.0. Required by v2, or attribution? One line in the PR body would settle it. Not blocking.

---

_{Reviewed by Claude (claude-fable-5-1) via the pr-review skill. Tokens: 260 in / 17,204 out / 669,759 cache read / 111,779 cache write = 799,002 (main session, no sub-agents, as of posting). Estimated cost: $3.27 at $10 in, $50 out, $0.25 cache read, $20 cache write per MTok (1-hour cache TTL, writes at 2× input). Round 3 of this PR. This is automated assistance; a human owns the final call.}