Skip to main content
Disclaimer: This project is currently in Beta, meaning features and APIs may evolve over time.
👉 Please report bugs or request new features by creating a GitHub issue.
The Upsun SDK for Node is now available! 🎉 We’re happy to introduce the official Upsun Node SDK, a modern and fully typed way to interact with the Upsun API from your Node.js applications. 👉 GitHub: https://github.com/upsun/upsun-sdk-node\ 👉 npm: https://www.npmjs.com/package/upsun-sdk-node This release expands the Upsun SDK ecosystem and follows the previously announced PHP SDK, bringing the same philosophy to the JavaScript and TypeScript world.

​
Bringing Upsun to the JavaScript ecosystem

Upsun provides a powerful and comprehensive API that allows you to manage projects, environments, infrastructure, and more. While the API is fully accessible over HTTP, building against raw endpoints requires:
  • Authentication handling
  • Request formatting
  • Response parsing
  • Error normalization
  • Keeping up with API structure changes
The upsun-sdk-node package removes that friction by providing a clean, typed, and developer-friendly abstraction that mirrors the official API structure. It is built directly on top of the official Upsun API: https://docs.upsun.com/api/

​
Installation

Install via npm: 
npm install upsun-sdk-node
The package works with modern Node.js environments and supports TypeScript out of the box.

​
Authentication

The SDK uses Upsun API tokens. Generate an API token from your Upsun account, store it securely, for example in an environment variable, and finally initialize the client: 
import { UpsunClient } from "upsun-sdk-node";

const client = new UpsunClient({
  token: process.env.UPSUN_API_TOKEN,
});
That’s it --- you’re ready to interact with the Upsun API.

​
Example: Listing Projects

const projects = await client.projects.list();
console.log(projects);

​
Example: Create environment variables

The SDK directly maps to API endpoints such as the environment variables operations: 
const acceptedResponse = await upsun.environments.createVariable(
  projectTestId, 
  environmentId,
  'MY_VARIABLE',
  'my_value',
  {
    isSensitive: true,
    visibleBuild: true,
    visibleRuntime: true,
  }
);
console.log(acceptedResponse);
The structure of the SDK closely follows the API to ensure predictability and clarity.

​
Design Goals

The Upsun Node.js SDK was designed with the following principles:
  • API-first design — stays close to the official API structure
  • Strong typing — first-class TypeScript support
  • Minimal abstraction — no hidden magic
  • Predictable method naming
  • Clear and structured error handling
The goal is not to hide the API, but to make it safer and more ergonomic to use in Node.js applications.

​
Use Cases

The SDK is particularly useful for:
  • CI/CD integrations
  • DevOps automation
  • Internal tooling
  • Infrastructure scripting
  • Custom dashboards
  • Platform integrations
If you’re automating workflows or building services around Upsun, this SDK is built for you.

​
Clear and helpful JSDoc

Every class, property, and method in the SDK is carefully documented.
The JSDoc comments are written to guide you through each endpoint, model, and expected parameter, making the SDK easy to navigate with IDE autocomplete and inline hints. This means developers can explore the SDK intuitively — just type client. and let your IDE show you what’s available.

​
Documentation

You can explore the source code: https://github.com/upsun/upsun-sdk-node

​
Growing the Upsun SDK Ecosystem

With the PHP SDK and now the Node.js SDK, Upsun continues to expand its official developer tooling. Our goal is to provide consistent, high-quality SDKs across languages while respecting each ecosystem’s conventions and best practices.

​
Contributing

Contributions are more than welcome! If you find bugs, have ideas, or want to add new API endpoints, please open a pull request or a GitHub issue.

​
Get Started Today

Install the SDK, generate an API token, and start building programmatically with Upsun.

​
Coming soon: SDKs for Python, and Go

The Upsun Advocacy team is also working on official SDKs for Python, and Go.
Each SDK will follow the same philosophy as the PHP and Node one — open-source, API-spec driven, and developer-friendly. Stay tuned for future announcements and beta releases on our GitHub organization.
Last modified on April 14, 2026