Neon TypeScript SDK

Neon TypeScript SDK

The @neondatabase/api-client TypeScript SDK is a typed wrapper around the Neon REST API. It provides methods for managing all Neon resources, including projects, branches, endpoints, roles, and databases.

For core concepts (Organization, Project, Branch, Endpoint, etc.), see what-is-neon.md.

Documentation

curl -H "Accept: text/markdown" https://neon.com/docs/reference/typescript-sdk

Installation

npm install @neondatabase/api-client

Authentication

import { createApiClient } from "@neondatabase/api-client";

const apiKey = process.env.NEON_API_KEY;
if (!apiKey) {
  throw new Error("NEON_API_KEY environment variable is not set.");
}

const apiClient = createApiClient({ apiKey });

Projects

List Projects

const response = await apiClient.listProjects({});
console.log("Projects:", response.data.projects);

Create Project

const response = await apiClient.createProject({
  project: { name: "my-project", pg_version: 17, region_id: "aws-us-east-2" },
});
console.log(
  "Connection URI:",
  response.data.connection_uris[0]?.connection_uri,
);

Get Project

const response = await apiClient.getProject("your-project-id");

Update Project

await apiClient.updateProject("your-project-id", {
  project: { name: "new-name" },
});

Delete Project

await apiClient.deleteProject("project-id");

Get Connection URI

const response = await apiClient.getConnectionUri({
  projectId: "your-project-id",
  database_name: "neondb",
  role_name: "neondb_owner",
  pooled: true,
});
console.log("URI:", response.data.uri);

Branches

Create Branch

import { EndpointType } from "@neondatabase/api-client";

const response = await apiClient.createProjectBranch("your-project-id", {
  branch: { name: "feature-branch" },
  endpoints: [{ type: EndpointType.ReadWrite, autoscaling_limit_max_cu: 1 }],
});

List Branches

const response = await apiClient.listProjectBranches({
  projectId: "your-project-id",
});

Get Branch

const response = await apiClient.getProjectBranch("your-project-id", "br-xxx");

Update Branch

await apiClient.updateProjectBranch("your-project-id", "br-xxx", {
  branch: { name: "updated-name" },
});

Delete Branch

await apiClient.deleteProjectBranch("your-project-id", "br-xxx");

Databases

Create Database

await apiClient.createProjectBranchDatabase("your-project-id", "br-xxx", {
  database: { name: "my-app-db", owner_name: "neondb_owner" },
});

List Databases

const response = await apiClient.listProjectBranchDatabases(
  "your-project-id",
  "br-xxx",
);

Delete Database

await apiClient.deleteProjectBranchDatabase(
  "your-project-id",
  "br-xxx",
  "my-app-db",
);

Roles

Create Role

const response = await apiClient.createProjectBranchRole(
  "your-project-id",
  "br-xxx",
  {
    role: { name: "app_user" },
  },
);
console.log("Password:", response.data.role.password);

List Roles

const response = await apiClient.listProjectBranchRoles(
  "your-project-id",
  "br-xxx",
);

Delete Role

await apiClient.deleteProjectBranchRole(
  "your-project-id",
  "br-xxx",
  "app_user",
);

Endpoints

Create Endpoint

import { EndpointType } from "@neondatabase/api-client";

const response = await apiClient.createProjectEndpoint("your-project-id", {
  endpoint: { branch_id: "br-xxx", type: EndpointType.ReadOnly },
});

List Endpoints

const response = await apiClient.listProjectEndpoints("your-project-id");

Start/Suspend/Restart Endpoint

// Start
await apiClient.startProjectEndpoint("your-project-id", "ep-xxx");

// Suspend
await apiClient.suspendProjectEndpoint("your-project-id", "ep-xxx");

// Restart
await apiClient.restartProjectEndpoint("your-project-id", "ep-xxx");

Update Endpoint

await apiClient.updateProjectEndpoint("your-project-id", "ep-xxx", {
  endpoint: { autoscaling_limit_max_cu: 2 },
});

Delete Endpoint

await apiClient.deleteProjectEndpoint("your-project-id", "ep-xxx");

API Keys

List API Keys

const response = await apiClient.listApiKeys();

Create API Key

const response = await apiClient.createApiKey({ key_name: "my-script-key" });
console.log("Key:", response.data.key); // Store securely!

Revoke API Key

await apiClient.revokeApiKey(1234);

Operations

List Operations

const response = await apiClient.listProjectOperations({
  projectId: "your-project-id",
});

Get Operation

const response = await apiClient.getProjectOperation(
  "your-project-id",
  "op-xxx",
);

Organizations

Get Organization

const response = await apiClient.getOrganization("org-xxx");

List Members

const response = await apiClient.getOrganizationMembers("org-xxx");

Create Org API Key

const response = await apiClient.createOrgApiKey("org-xxx", {
  key_name: "ci-key",
  project_id: "project-xxx", // Optional: scope to project
});

Invite Member

import { MemberRole } from "@neondatabase/api-client";

await apiClient.createOrganizationInvitations("org-xxx", {
  invitations: [{ email: "dev@example.com", role: MemberRole.Member }],
});

Error Handling

async function safeApiOperation(projectId: string) {
  try {
    const response = await apiClient.getProject(projectId);
    return response.data;
  } catch (error: any) {
    if (error.isAxiosError) {
      const status = error.response?.status;
      switch (status) {
        case 401:
          console.error("Check your NEON_API_KEY");
          break;
        case 404:
          console.error("Resource not found");
          break;
        case 429:
          console.error("Rate limit exceeded");
          break;
        default:
          console.error("API error:", error.response?.data?.message);
      }
    }
    return null;
  }
}