Coolify TypeScript SDK

Unofficial, strongly-typed client for the Coolify API. The SDK mirrors the REST resources that appear in the official docs inside docs/api_docs.txt and wraps the HTTP calls with helpful defaults, typed helpers, and ergonomic groupings.

Features

• Token-based authentication baked into every request.
• Resource-oriented API surface (applications, services, projects, servers, databases, securityKeys, teams, resources, system).
• Strong typing for documented request bodies and common responses such as environment variable CRUD and deployment queue operations.
• Generic overrides to support custom response typing when the public docs do not publish schemas.
• Escape hatches through client.request for endpoints that are not yet wrapped.

Installation

This repository ships consumable TypeScript directly. Install dependencies and build the project:

npm install
npm run build

Usage

import { CoolifyClient } from "coolify-sdk";

const client = new CoolifyClient({
  baseUrl: "https://coolify.example.com/api",
  token: process.env.COOLIFY_TOKEN!,
});

// List services with strongly typed env helpers
const services = await client.services.list();

// Work with environment variables on an application
const envs = await client.applications.listEnvironmentVariables("app-uuid");
await client.applications.createEnvironmentVariable("app-uuid", {
  key: "NODE_ENV",
  value: "production",
  is_preview: false,
});

// Kick off a restart and inspect the queued deployment UUID
const restart = await client.applications.restart("app-uuid");
console.log(restart.message, restart.deployment_uuid);

// Use the generic override when you expect a custom payload:
interface ProjectSummary { uuid: string; name: string; }
const projects = await client.projects.list<ProjectSummary[]>();

// Raw requests are also available.
const raw = await client.request<{ message: string }>({
  method: "GET",
  path: "/services/{uuid}/stop",
  pathParams: { uuid: "service-uuid" },
});

Configuration

| Option | Type | Default | Description | | --- | --- | --- | --- | | baseUrl | string | http://localhost:8000/api | Coolify base API URL (without /v1). | | token | string | required | API token generated in Coolify. | | fetch | FetchLike | globalThis.fetch | Custom fetch implementation (for Node prior to 18, testing, etc.). | | apiVersion | string | v1 | API version prefix automatically appended to all routes except /health and /feedback. | | defaultHeaders | Record<string, string> | { Accept: "application/json" } | Additional headers merged into every request. |

Resources

• applications: delete, logs, environment variables (CRUD/bulk), lifecycle (start/stop/restart).
• databases: list, get, start/stop/restart.
• projects: list/create/update/delete, environment management.
• services: list/create/update/delete, environment variables, lifecycle helpers.
• servers: list/create/update/delete, resources/domains/validate.
• securityKeys: list/create/update/delete and direct uuid accessors.
• teams: list teams, team members, and the currently authenticated team context.
• resources: list all resources linked to the account.
• system: health/enable/disable/version helpers.

The client.request escape hatch exposes the low-level caller in case you need endpoints that are not yet modeled.

Error Handling

Failed responses throw a CoolifyError that includes:

• status: HTTP status code.
• request: method, URL, and serialized body that were sent.
• payload: best-effort parsed response body or text.

Testing

After installing dependencies:

npm run build

The command strictly type-checks and emits ESM output in dist/.

Release Workflow

• Run npm run changeset whenever you make a user-facing change; follow the prompt to record the release note.
• Commit the generated .changeset file alongside your code and merge into main.
• The Release GitHub Action will open or update a release PR. When that PR is merged, it publishes the package to npm using the npm run release script.
• Configure the repository secrets NPM_TOKEN (scoped for publishing coolify-sdk) so the workflow can push to npm.

License

MIT — see LICENSE if you add one.