{"slug": "introducing-neon-sdk-our-new-typescript-client-for-the-neon-api", "title": "Introducing @neon/sdk, our new TypeScript client for the Neon API", "summary": "Neon has released @neon/sdk, a new TypeScript client for the Neon API that provides a generated core with an ergonomic layer for project creation, branch management, and project transfers. The SDK includes features like readiness polling, snapshot restoration with preview, and project transfer across organizations, aiming to simplify programmatic automation on Neon's serverless Postgres platform.", "body_md": "Today, we're introducing [ @neon/sdk](https://www.npmjs.com/package/@neon/sdk), the best way to work with the\n\n[Neon API](https://neon.com/docs/reference/api-reference)from TypeScript: project creation, branch & database management, project transfers and much more.\n\nIn this post, we'll highlight some of `@neon/sdk`\n\ncapabitilies, cover how the package is structured, explain why we built it in the age of AI and discuss when you should use it.\n\nMost importantly, you can install `@neon/sdk`\n\ntoday:\n\nAnd use ergonomic functions like `createAndConnect`\n\nto provision a Neon project, wait for the provisioning operations to finish and hand you back a ready-to-use Postgres connection string, all in a single call:\n\nNow let's dig in.\n\n## A generated core with an ergonomic layer on top\n\n`@neon/sdk`\n\nis fetch-based, zero dependencies and ESM-only. The raw client is generated from our [OpenAPI spec](https://neon.com/api_spec/release/v2.json) with [Hey API](https://heyapi.dev), so every endpoint maps one-to-one to a TypeScript function. Shout-out to Hey API maintainer [Lubos](https://x.com/mrlubos) for the input and support! On top of that, we built a higher-level layer that provides ergonomics on top: retries, readiness polling, pagination, better errors, and multi-step workflows.\n\nSo the package ships two layers:\n\n: the high-level ergonomic client, organized into resource namespaces like`createNeonClient`\n\n`neon.projects`\n\nand`neon.branches`\n\n.: the low-level generated surface, every endpoint as a standalone, tree-shakeable function.`raw`\n\nTake readiness polling as an example. 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`\n\nthat you'd normally poll yourself until the resource is ready. `@neon/sdk`\n\noffers an abstraction that does that polling behind the scenes, so a call only resolves once the resource is actually ready. `createAndConnect`\n\ndoes this by default and you can opt any other mutation into the same behavior.\n\nWe hope `createNeonClient`\n\ncovers 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.\n\nLet's walk through a few of the higher-level workflows we added!\n\n### Restore a snapshot and preview it before you commit\n\n[Neon Snapshots](https://neon.com/docs/guides/backup-restore#create-snapshots-manually) are point-in-time copies of a branch's schema & data that you can restore from later. Restoring one onto an existing branch is a two-step operation: Neon restores the snapshot to a new branch, then finalizes it by moving the target branch's compute onto the restored data, so your connection string doesn't change when restoring from a snapshot.\n\nThe `restore`\n\nfunction combines both steps into one call with an optional `preview`\n\ncallback: it restores the not-yet-finalized branch, runs your callback against it, then finalizes if you return `true`\n\nor discards the preview branch if you return `false`\n\n.\n\nNo manual finalize step and no orphaned branch to clean up when you abort. Behind that one call, the SDK waits for the restore to be ready and then finalizes it (commit) or deletes the preview branch (abort) for you, so you don't have to wire up the operatino readiness polling and branch cleanup yourself.\n\n### Transfer projects across organizations\n\nIf you're building a platform on Neon, we usually recommend you to set up two Neon organizations - one for your free plan and one for your paid plan: you provision each user's project in the free-plan org, then transfer it to a paid org once they upgrade, so your Neon Postgres fleet stays organized and billed cleanly across the two plans. The `transfer`\n\nfunction makes this super easy:\n\n### Create a branch with its own compute\n\nIf you create a Neon branch through the API, you have to chain two calls:\n\n- Create the branch\n- Provision compute for the branch\n\nIf you're used to the Neon UI, this is done automatically for you, but over the REST API it's split into two calls, which usually takes both devs and agents a few attempts to get right. `createWithCompute`\n\ncreates the branch, spins up a read-write endpoint, waits for it to be ready and returns a connection string, all in one call:\n\nThese are just three of the many workflows we added to make working with the Neon REST API as easy as possible for you and your agent! That said, you can always reach for the raw API client:\n\n### Drop down to the raw client\n\nThe ergonomic namespaces don't wrap every endpoint and sometimes you just want the exact generated function. For those, the `raw`\n\nlayer exposes every endpoint 1:1. Pass `neon.client`\n\nso the raw call reuses the client's auth:\n\n## Why we built a new client\n\nAn expansive open APIs matters more than ever. 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](https://neon.com/blog/slop-fork-neon) and rebuilt most of the dashboard on top of the public API alone. In fact, I've already moved that [Neon Slop Fork](https://github.com/andrelandgraf/neon-slop-fork) over to `@neon/sdk`\n\nunder the hood.\n\nWe'd shipped a TypeScript client before this one: `@neondatabase/api-client`\n\n, generated with [openapi-typescript](https://openapi-ts.dev/). It did the job, but it was auto-generated and published straight from our private cloud platform repo, so there was no open source repo where we could add to it directly. That's why it stayed a thin generated wrapper and started to show its age (axios-based, no errors as values, etc.)\n\nWe think a type-safe layer on top of the raw REST API is worth a lot for developers and agents. It abstracts away the async operations and exposes ready-made workflows for the things that would otherwise take you or your agent a few attempts to get right, like creating a project and getting back a live connection string, or previewing a restore before you commit it.\n\nUltimately, we hope `@neon/sdk`\n\nmakes building on Neon more productive and more enjoyable, for you and your agents.\n\n## When to use @neon/sdk\n\nWe have the [Neon MCP server](https://neon.com/docs/ai/neon-mcp-server) and [CLI](https://neon.com/docs/cli) for local development and they shine when your coding agent is working right there in your editor or terminal. But `@neon/sdk`\n\nis what you should reach for whenever you're integrating Neon programmatically. That covers CI/CD where the CLI isn't enough, more sophisticated dev scripts and full platforms on Neon.\n\nNotabely, the Neon open API is used by platforms like Replit, Netlify DB, Laravel Cloud and Vercel's [marketplace integration](https://vercel.com/marketplace/neon) to provision and manage fleets of Neon databases. 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](https://neon.com/docs/guides/consumption-metrics) and much more.\n\n## Give it a try\n\nFor any TypeScript project - a script, a CI/CD job, a backend - install it and go:\n\nIf you're on the old `@neondatabase/api-client`\n\n, consider moving to `@neon/sdk`\n\nif you like what you see. However, there is no rush - we're not deprecating `@neondatabase/api-client`\n\nany time soon!\n\nBuilding an agent platform on Neon? Our [neon-for-agent-platforms](https://github.com/neondatabase/neon-for-agent-platforms) agent skill is already educated on `@neon/sdk`\n\n, with runnable scripts for provisioning, branching, snapshots, project transfer and consumption metrics:\n\nAnd if you haven't already, take a look at the [Neon Agent Plan](https://neon.com/programs/agents), with dedicated pricing for your agentic or cloud platform building on Neon.\n\nHave feedback or run into something missing? Drop into the [Neon Discord](https://discord.gg/HjupxCjXXp) and let us know.\n\nHappy coding!", "url": "https://wpnews.pro/news/introducing-neon-sdk-our-new-typescript-client-for-the-neon-api", "canonical_source": "https://neon.com/blog/neon-sdk", "published_at": "2026-07-13 12:00:00+00:00", "updated_at": "2026-07-18 15:53:17.033158+00:00", "lang": "en", "topics": ["developer-tools"], "entities": ["Neon", "@neon/sdk", "Hey API", "Lubos"], "alternates": {"html": "https://wpnews.pro/news/introducing-neon-sdk-our-new-typescript-client-for-the-neon-api", "markdown": "https://wpnews.pro/news/introducing-neon-sdk-our-new-typescript-client-for-the-neon-api.md", "text": "https://wpnews.pro/news/introducing-neon-sdk-our-new-typescript-client-for-the-neon-api.txt", "jsonld": "https://wpnews.pro/news/introducing-neon-sdk-our-new-typescript-client-for-the-neon-api.jsonld"}}