Python 3.8+

Lix.li Python SDK

Official Python SDK for the Lix.li URL shortening and link analytics API. Built with dataclasses, type hints, and clean keyword arguments. Create short links, manage groups, and track clicks with Pythonic simplicity.

GitHub PyPI

from lix_sdk import Client

client = Client('lix_live_xxx')

result = client.links().create('https://example.com')
print(result.link.short_url)
# https://lix.li/a3b7k2
print(result.usage.remaining)
# 42

Features

Everything you need to manage links in Python

Built with dataclasses, type hints, and clean keyword arguments. Pythonic by design.

Link Management

Create, get, update, delete, and list short links. Full CRUD with keyword arguments and optional defaults.

Group Management

Organize links into groups. Create rotating groups for A/B testing landing pages. Full CRUD with typed dataclass responses.

Account & Usage API

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

Dataclass DTOs

Every API response is a @dataclass with full type hints. Clean repr, IDE autocomplete, and natural attribute access.

Typed Errors

7 dedicated exception classes extending a base LixException. Catch what you need, access validation error data in .data.

Injectable Session

Pass your own requests.Session for custom timeouts, retries, or testing. Falls back to a default session.

Quick Start

Get started in 30 seconds

Requires Python 3.8+ and requests. Install with pip and start shortening URLs immediately.

Python 3.8+ MIT License

Install via pip

Add the SDK to your Python environment.

 pip install lix-sdk

Instantiate the client

Pass your API key. Optionally provide a custom requests.Session for advanced control.

from lix_sdk import Client

client = Client('lix_live_xxx')

# With custom session
import requests
session = requests.Session()
session.headers.update({'X-Custom-Header': 'value'})
client = Client('lix_live_xxx', session=session)

Create your first link

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

result = client.links().create('https://example.com')
print(result.link.short_url)
# https://lix.li/a3b7k2
# API links used: 42 / 100
print(result.usage.used, '/', result.usage.limit)

Links API

Full link lifecycle in Python

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

# Create a basic link
result = client.links().create('https://example.com')
print(result.link.short_url)

# With custom alias and UTM
result = client.links().create(
    'https://example.com',
    alias='my-link',
    title='My Page Title',
    tags=['sale', 'promo'],
    utm={'utm_source': 'google', 'utm_medium': 'email', 'utm_campaign': 'summer'},
    tracking_pixel_ids=[1001, 1002],
    is_public=True,
)

# Password protection + expiration
result = client.links().create(
    'https://example.com',
    password='secret123',
    active_before_datetime='2026-12-31T23:59:59+00:00',
)

# Update a link
updated = client.links().update(79697, title='New Title')
print(updated.link.title)

create(url, ...) Create a short link with keyword args: alias, UTM, tags, password, expiration, tracking pixels.
get(id) Retrieve a single link by ID with full metadata, group, tags, and status.
update(id, ...) Update any link field via keyword args: URL, title, group, tags, UTM, password, visibility.
delete(id) Soft-delete a link by ID. Returns None on success.
list(limit, from_id) Paginated list with Links dataclass containing ResponseMeta.

Pagination example: client.links().list(limit=20, from_id=79500) returns the next 20 links with ResponseMeta containing total count and next URL. Omit both for API defaults.

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(name, ...) Create a group with name, optional description, and rotating mode.
get(id) Fetch a group by ID with all metadata.
update(id, ...) Rename, update description, or toggle rotation mode.
delete(id) Remove a group by ID.
list(limit, from_id) Paginated list with typed Groups dataclass and ResponseMeta.

# Create a regular group
group = client.groups().create('Marketing')
print(group.name, group.url)

# Create a rotating group for A/B testing
group = client.groups().create(
    'Landing Pages',
    description='Rotating landing pages',
    is_rotate=True,
)

# Update group
group = client.groups().update(
    10,
    description='Updated description',
)

# List with pagination
page = client.groups().list(limit=10, from_id=1000)
for g in page.groups:
    print(g.name, g.url)
print(page.meta.total)

Profile & Usage API

Account and usage details

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

profile = client.profile().me()

# Account info
print(profile.client.name, profile.client.email)
print(profile.user.email)

# Plan details
print(profile.plan.name, profile.plan.end_datetime)

# Usage limits
print(profile.usages.links.remaining)
print(profile.usages.api_links.used)
print(profile.usages.mass_links.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 Pythonic control

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

from lix_sdk import (
    ValidationException,
    NotFoundException,
    UnauthorizedException,
    RateLimitException,
    ServerException,
)

try:
    result = client.links().create('invalid-url')
except ValidationException as e:
    # Field-level validation errors
    print('Validation:', e.data)
except NotFoundException:
    print('Not found')
except UnauthorizedException:
    # Invalid API key
except RateLimitException:
    # Too many requests — retry after
except ServerException:
    # 5xx server error
except LixException as e:
    # Generic SDK error
    print('Error:', e)

ValidationException

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

UnauthorizedException

401 — Invalid API key or missing auth.

NotFoundException

404 — Link or group not found.

RateLimitException

429 — Rate limit exceeded.

ServerException

500 — Unexpected Server-side error.

HttpClientException

Network / transport failure.

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

Ecosystem

Official SDKs for every stack

The same clean API, idiomatically implemented in your language of choice.

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

JS SDK

Promise-based JavaScript SDK for Node.js and browser environments. Create and manage short links with a clean developer experience.

GitHub Docs

Ready to shorten links in Python?

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

GitHub Repository PyPI Create API Key