Lix.li JavaScript SDK — Official Node.js & Browser Client for URL Shortening API

Features

Everything you need for URL Shortener API integrations in Java Script

Built with async/await, plain class-based DTOs, and a swappable fetch function for Node.js or browser.

Link Management

Create, get, update, delete, and list short links. Full CRUD with typed class responses.

Group Management

Organize links into groups. Create rotating groups for A/B testing landing pages.

Account & Usage API

Fetch account profile, plan details, and real-time usage limits for links and API calls.

Class-based DTOs

Every API response is a plain JavaScript class instance. No raw objects — predictable structure with dot-notation access.

Typed Exceptions

6 dedicated exception types for validation, authorization, rate limits, server errors, and transport failures.

Custom Fetch

Inject any fetch-compatible function. Works with Node.js fetch, undici, or browser fetch out of the box.

Quick Start

Get started in 30 seconds

Works in any Node.js or browser environment with fetch support. No heavy dependencies — just a clean HTTP client layer.

Node.js 18+ MIT License Browser

1

Install via npm

Add the SDK to your Node.js or browser project.

 npm install lix-url

2

Instantiate the client

Pass your API key. Optionally inject a custom fetch function for testing or edge runtimes.

const { Client } = require('lix-url');
const client = new Client('lix_live_xxx');

// With custom fetch (e.g., for testing)
const client = new Client('lix_live_xxx', myFetchFn);

3

Create your first link

Shorten a URL and get back a typed LinkShortenResult with the short URL and usage info.

const result = await client.links().create('https://example.com');
console.log(result.link.shortUrl);
// https://lix.li/a3b7k2
// Links used: 42 / 100
console.log(result.usage.used, '/', result.usage.limit);

Links API

Full link lifecycle in JavaScript

Create short links with custom aliases, UTM parameters, tracking pixels, password protection, and expiration dates. Every operation returns a typed class instance.

// Create a basic link
const result = await client.links().create('https://example.com');

// With custom alias and UTM
const result = await client.links().create(
    'https://example.com',
    'summer-sale',           // alias
    'My Summer Sale',        // title
    null,                    // groupId
    ['marketing', '2026'],   // tags
    [],                      // meta
    {                        // utm
        source: 'newsletter',
        medium: 'email',
        campaign: 'summer-sale',
    },
    [1, 2],                 // trackingPixelIds
    null,                    // activeBeforeDatetime
    null,                    // password
    true                     // isPublic
);

// Password protection + expiration
const result = await client.links().create(
    'https://example.com',
    null, null, null, [], [], [], [],
    '2026-12-31T23:59:59Z',  // activeBeforeDatetime
    'secret123'              // password
);

create() Create short links with aliases, UTM tags, tracking pixels, passwords, expiration dates, and custom settings.
get() Retrieve a short link with metadata, tags, groups, usage data, and current status.
update() Update any link field: URL, title, group, tags, UTM, password, visibility.
delete() Soft-delete a link by ID. Returns void on success.
list() Browse links with pagination, filtering, and typed collection responses. Paginated list with limit and fromId. Returns Links DTO with meta.

Pagination example: $client->links()->list(limit: 100, fromId: 500) returns the next 100 links starting after ID 500, with ResponseMeta containing total count and next URL.

Groups API

Organize and rotate links

Groups help you categorize links by campaign, team, or project. Rotating groups enable A/B testing by distributing traffic across multiple links.

create() Create a group with name, optional description, and rotating mode.
get() Fetch a group by ID with all metadata.
update() Rename, update description, or toggle rotation mode.
delete() Delete a group while keeping link data intact.
list() Browse groups with pagination and typed collection responses.

// Create a regular group
const group = await client.groups().create('Marketing');
console.log(group.name);

// Create a rotating group for A/B testing
const group = await client.groups().create(
    'Landing Pages',
    null,
    true   // isRotate
);

// Update group
const group = await client.groups().update(
    10,
    null,
    'Updated description'
);

// List with pagination
const response = await client.groups().list(10, 1000);
for (const group of response.groups) {
    console.log(group.name);
}

Profile & Usage API

Account and usage details

Fetch your profile, plan, and real-time usage limits — all returned as nested class instances with full property access.

const profile = await client.profile().me();

// Account info
console.log(profile.client.name, profile.client.email);
console.log(profile.user.email);

// Plan details
console.log(profile.plan.name, profile.plan.endDatetime);

// Usage limits
console.log(profile.usages.links.remaining);
console.log(profile.usages.apiLinks.used);
console.log(profile.usages.massLinks.limit);

Client

Organization and account metadata.

User

Authenticated user information and account details.

Plan

Current subscription and billing period.

Usage

API limits, link quotas, and remaining usage.

Error Handling

7 typed exceptions for precise control

Catch exactly what you need. All exceptions extend LixException. ValidationException includes the full field-level error data in err.data.

const {
    ValidationException,
    NotFoundException,
    UnauthorizedException,
    RateLimitException,
    ServerException
} = require('lix-url');

try {
    await client.links().create('invalid-url');
} catch (err) {
    if (err instanceof ValidationException) {
        // Field-level validation errors
        console.error('Validation:', err.data);
    } else if (err instanceof NotFoundException) {
        console.error('Not found:', err.message);
    } else if (err instanceof UnauthorizedException) {
        // Invalid API key
    } else if (err instanceof RateLimitException) {
        // Too many requests — retry after
    } else if (err instanceof ServerException) {
        // 5xx server error
    } else {
        // Generic Lix or network error
        console.error('Error:', err.message);
    }
}

ValidationException

400 — Invalid input. Access err.data for field errors.

UnauthorizedException

401 — Missing, invalid, or expired API credentials.

NotFoundException

404 — Link, group or resource not found.

RateLimitException

429 — Rate limit exceeded.

ServerException

500 — Unexpected server error.

HttpClientException

Network / transport failure.

All exceptions extend LixException, which extends native Error. Catch the base class for any SDK error, or target specific classes for granular handling.

Ecosystem

Official SDKs for popular stacks

Use the same Lix.li API from PHP, JavaScript, Python, or Go with SDKs tailored to each ecosystem.

Python SDK

Typed Python client for short links, groups, analytics, and automation. Built for modern Python applications and workflows.

GitHub Docs

Go SDK

Native Go SDK with typed structures, context support, and idiomatic error handling for URL Shortener API integrations.

GitHub Docs

PHP SDK

Modern PHP SDK with typed DTOs, readonly models, dedicated exceptions, and Composer-first installation.

GitHub Docs

Ready to shorten links in JavaScript?

Install the SDK, get your API key, and start creating short links in under a minute.

GitHub Repository npm Create API Key