Runpod REST API v2 — TypeScript SDK

A typed TypeScript/JavaScript client for Runpod REST API v2 (https://api.runpod.io/v2). Manage pods, clusters, Serverless endpoints, templates, network volumes, registries, catalog, SSH keys, and billing.

REST v2 API docs · OpenAPI spec · Runpod plugin · MCP server

Supports Node.js 20+, ESM, and CommonJS. For Serverless job submission and results, use the existing runpod-sdk.

Using an AI agent instead?

The Runpod plugin adds Runpod skills and tools to your agent. In Claude Code:

/plugin marketplace add runpod/runpod-plugins-official
/plugin install runpod@runpod
/reload-plugins

Authenticate through /mcp → runpod → Sign in with Runpod. Install for other agents.

For MCP tools only, run the guided installer and follow its connection/authentication prompts:

npx @runpod/mcp-server@latest add

These alternatives let an agent manage Runpod without integrating this SDK.

Install from npm

Install the SDK in your app:

npm install @runpod/typescript-api-sdk

Or with pnpm:

pnpm add @runpod/typescript-api-sdk

Then create a client with your API key. Node.js 20+ is required; Python and the source build tools are not needed to use the npm package.

Build from source

To build from source, install Node.js 24 and pnpm 11. Python is only needed when regenerating types or running the spec tests.

From the SDK checkout:

pnpm install --frozen-lockfile
pnpm build
cp .env.example .env

Set RUNPOD_API_KEY in .env, then run a read-only request to list GPU types:

node --env-file=.env examples/catalog.mjs

Install a local build

Create a local package from the SDK checkout:

npm pack

Then install that file in your app's directory, using the tarball path printed by npm pack:

npm install /path/to/package.tgz

Use it in your app

After installing from npm or a local build, pass your API key when creating a client and make a request:

import { createRunpodClient } from "@runpod/typescript-api-sdk";

const client = createRunpodClient({ apiKey: "YOUR_API_KEY" });
const { data, response } = await client.GET("/v2/catalog/gpus", {
  signal: AbortSignal.timeout(15_000),
});

if (!response.ok) throw new Error(`Runpod request failed: ${response.status}`);
if (!data) throw new Error("Runpod returned no data");
console.log(data.gpus);

The client retries transient failures by default; pass { retry: false } to disable retries. Use response.ok to check HTTP status. Network, timeout, and parsing failures reject the promise. A 30-second deadline covers retries and response-body consumption; configure timeoutMs or set it to false for long-lived streams. The SDK does not load .env automatically. Keep API keys in server-side code.

One API key per client

Each call to createRunpodClient creates an independent client. Pass apiKey to configure credentials for that instance; requests send it as Authorization: Bearer <apiKey>.

import { createRunpodClient } from "@runpod/typescript-api-sdk";

const clientA = createRunpodClient({ apiKey: "YOUR_FIRST_API_KEY" });
const clientB = createRunpodClient({ apiKey: "YOUR_SECOND_API_KEY" });

const podsA = await clientA.GET("/v2/pods"); // Uses the first key
const podsB = await clientB.GET("/v2/pods"); // Uses the second key

Create as many clients as you need. Each keeps its own credentials and options; creating another client does not change existing clients. Load real keys from server-side configuration or a secret store rather than committing them to code.

If you omit apiKey, the client reads RUNPOD_API_KEY from the environment when it is created. An explicit apiKey takes precedence. For example:

const client = createRunpodClient(); // Uses RUNPOD_API_KEY

More

• Client guide: options, errors, retries, CommonJS, and log streams.
• Logging guide: structured events, cancellation, and parser limits.
• Examples: runnable catalog and pod-log requests.
• Development: tests, type generation, and spec-update automation.

MIT — License · Third-party notices