---
title: "TypeScript SDK"
description: "Use the Apache-2.0 HeliosDB TypeScript SDK against the HeliosDB Lite REST API: build from source, authenticate with a JWT, run SQL and manage branches."
---

# TypeScript SDK

TypeScript/JavaScript client for the HeliosDB-Lite REST API.

## Installation

> The SDKs are Apache-2.0 and developed in the public [HeliosDatabase/HeliosDB-SDKs](https://github.com/HeliosDatabase/HeliosDB-SDKs) repository. They are not published to package registries yet, so install from source as shown. See [SDKs & Integrations](https://www.heliosdb.com/docs/lite/api/sdks/) and the SDK README for the full client API.

```bash
git clone https://github.com/HeliosDatabase/HeliosDB-SDKs
cd HeliosDB-SDKs/sdks/typescript && npm install && npm run build && cd -
npm install ./HeliosDB-SDKs/sdks/typescript
```

The locally installed package is named `@heliosdb/client`.

## Quick Start

Every Lite `/v1` route needs a JWT signed with the server's `HELIOSDB_JWT_SECRET`; see [Authentication](https://www.heliosdb.com/docs/lite/website/getting-started/authentication/) for how to mint one.

```typescript
import { HeliosDB } from '@heliosdb/client';

const db = new HeliosDB({
  url: 'http://localhost:8080',
  jwtToken: process.env.HELIOSDB_TOKEN,
});

// Query the main branch (POST /v1/branches/main/query)
const result = await db.query('SELECT * FROM users WHERE id = $1', [1]);
console.log(result.toObjects());
```

## Branching

```typescript
// POST /v1/branches
await db.createBranch('dev', { fromBranch: 'main' });

// Query a branch
await db.query('SELECT count(*) FROM users', [], { branch: 'dev' });
```

Branches can also be managed in SQL: `CREATE DATABASE BRANCH dev FROM main AS OF NOW`.

## Vector Search and Agent Memory

The SDK has vector-store and agent-memory helpers. The matching Lite REST endpoint groups are planned, so these helpers return a not-implemented error against Lite today. Run vector search in SQL instead; see [Vector Search](https://www.heliosdb.com/docs/lite/features/vector-search/).

See the [REST API Reference](https://www.heliosdb.com/docs/lite/website/api/readme/) for the routes Lite serves.