@neon/sdk is our new TypeScript client for the Neon API. It's fetch-based, zero dependencies and ESM-only, generated from our OpenAPI spec with an ergonomic layer on top. It replaces @neondatabase/api-client.

npm install @neon/sdk

Here's the whole point of the ergonomic layer in one example. createAndConnect provisions a project, waits for the provisioning operations to finish and hands you back a ready-to-use connection string, all in a single call:

import { createNeonClient } from "@neon/sdk";

const neon = createNeonClient({ apiKey: process.env.NEON_API_KEY! });

const { data, error } = await neon.projects.createAndConnect({
  name: "my-app",
});
if (error) throw error;

const { project, connectionString } = data;

The Neon API provisions real infrastructure and a lot of that work happens in the background, so most mutations don't hand you a ready-to-use resource. They return operations that you'd normally poll yourself until the resource is ready. @neon/sdk offers an abstraction that does that polling behind the scenes, so a call only resolves once the resource is actually ready. createAndConnect does this by default and you can opt any other mutation into the same behavior.

Under the hood the client is generated from our OpenAPI spec with Hey API, so it stays 1:1 with the real API. On top of that generated surface we built an ergonomic layer that handles the annoying parts for you: authenticate once, get typed { data, error } results, automatic retries on safe statuses, readiness polling, auto-pagination and a few multi-step workflows. So the package really ships two layers:

  • createNeonClient: the ergonomic client, organized into resource namespaces like neon.projects and neon.branches.
  • raw: the full generated surface, every endpoint as a standalone, tree-shakeable function.

We hope createNeonClient covers most of what you need to build platforms and programmatic automations on Neon: a type-safe, ergonomic way to use Neon's capabilities. That said, you can always reach for the raw API methods directly.

Let's walk through a few of the higher-level workflows we added to the ergonomic client!

Restore a snapshot and preview it before you commit

Restoring a snapshot onto an existing branch swaps out its data, so it's the kind of thing you want to check before it's final. restore supports a transaction-style flow: pass a preview callback and the SDK restores onto a temporary, not-yet-finalized branch, runs your callback against it, then commits the restore if you return true or throws the preview branch away if you return false.

await neon.snapshots.restore(projectId, snapshotId, {
  targetBranchId,
  preview: async (branch) => {
    // inspect the restored (not-yet-finalized) branch
    const ok = await runChecks(branch);
    return ok; // true commits the restore, false rolls it back
  },
});

No manual finalize step and no orphaned branch to clean up when you abort.

Transfer projects across organizations

A common pattern: you start a user's project in a sponsored org, then move it to a paid org once they upgrade.

await neon.projects.transfer({
  fromOrgId: sponsoredOrgId,
  toOrgId: paidOrgId,
  projectIds: ["late-frost-12345"],
});

Errors your way: return or throw

By default, every method resolves to a discriminated { data, error } envelope, so you don't need a try/catch. The error channel carries a typed hierarchy, so you can branch on error.kind:

const { data, error } = await neon.projects.get("late-frost-12345");

if (error) {
  if (error.kind === "not_found") return null;
  throw error;
}

return data; // narrowed to Project

If you'd rather work with exceptions, set throwOnError and methods return the bare resource and throw instead. The return types narrow accordingly.

const neon = createNeonClient({
  apiKey: process.env.NEON_API_KEY!,
  throwOnError: true,
});

const project = await neon.projects.get("late-frost-12345"); // Project, throws on error

The ergonomic namespaces don't wrap every endpoint and sometimes you just want the exact generated function. Everything is available raw. Pass neon.client so the raw call reuses the client's auth:

import { raw } from "@neon/sdk";
// or, for guaranteed tree-shaking:
// import { getProjectBranchSchema } from "@neon/sdk/raw";

const { data } = await raw.getProjectBranchSchema({
  client: neon.client,
  path: { project_id, branch_id },
});

Why we built a new client

We'd had @neondatabase/api-client for a while, generated with openapi-typescript, but it never shipped as an open source repo. It was generated and published straight out of our private cloud platform repo and it had started to show its age: Axios-based rather than fetch and no hand-written ergonomic layer on top.

The deeper reason is where developer tools are heading. Agents are much better at using APIs than at clicking through dashboards. Having an agent computer-use its way through your console is slower, more fragile and more expensive than handing it an API key and letting it call your endpoints directly. That's why an expansive, open REST API matters more than ever. At Neon, we aim to expose every platform capability through our open API and follow the OpenAPI spec. If you can do it in the Neon console, you should be able to do it through the API too. I made that case recently when I slop forked the Neon console and rebuilt most of the dashboard on top of the public API alone. In fact, I've already moved that Neon Slop Fork over to @neon/sdk under the hood.

The same open API powers the platforms built on Neon. Replit, Netlify DB, Laravel Cloud, Vercel's marketplace integration and others don't get a special API. They build on the same endpoints and capabilities of our open API. All it takes is an API key: provision databases, configure them, enable Neon Auth, transfer projects across organizations, pull fine-grained project and branch-level consumption metrics and much more.

A REST API isn't always the right level to work at, though. For local development, the Neon MCP server and CLI both let your coding agent provision and manage Postgres without leaving your agentic editor/terminal/harness. The CLI is also handy for some CI/CD work. But when you're building a platform on Neon, slop forking the console or wiring up more expansive CI/CD pipelines or dev scripts, you'll want to call the endpoints directly. That's where you should reach for our new @neon/sdk.

Give it a try

If you're building an agent platform on Neon, our neon-for-agent-platforms agent skill is already educated on how to use @neon/sdk. It ships runnable scripts for provisioning, branching, snapshots, project transfer and consumption metrics, all on top of the new client.

Install the skill:

npx skills add neondatabase/neon-for-agent-platforms

Install the SDK:

npm install @neon/sdk

If you're on the old @neondatabase/api-client, this is the client to move to. But don't worry, we don't plan to deprecate @neondatabase/api-client any time soon.

Have feedback or run into something missing? Drop into the Neon Discord and let us know.

Happy coding!