shrtnr 1.0.0

SDK for the shrtnr URL shortener API

shrtnr

Python SDK for shrtnr, a self-hosted URL shortener on Cloudflare Workers. Create short links, manage slugs, and read click analytics.

Install

pip install shrtnr

Quick start

from shrtnr import Shrtnr

client = Shrtnr(base_url="https://your-shrtnr.example.com", api_key="sk_your_api_key")

link = client.links.create(url="https://example.com/very-long-path")
print(link.slugs[0].slug)  # "a3x9"

Async usage:

import asyncio
from shrtnr import AsyncShrtnr

async def main():
    async with AsyncShrtnr(base_url="https://your-shrtnr.example.com", api_key="sk_...") as client:
        link = await client.links.create(url="https://example.com")
        print(link.id)

asyncio.run(main())

Configuration

Shrtnr(
    base_url="https://your-shrtnr.example.com",  # required
    api_key="sk_...",                             # required; from the admin dashboard
    timeout=30.0,                                 # optional; seconds (default: 30)
    http_client=custom_httpx_client,              # optional; inject a custom httpx.Client
)

AsyncShrtnr accepts the same parameters, but takes an httpx.AsyncClient for http_client.

Both classes work as context managers:

with Shrtnr(base_url="...", api_key="sk_...") as client:
    links = client.links.list()

Resources

Links (client.links)

Method	Description
get(id, *, range=None)	Get a link with click count
list(*, owner=None, range=None)	List all links
create(*, url, label=None, slug_length=None, expires_at=None, allow_duplicate=None)	Create a short link
update(id, *, url=None, label=None, expires_at=None)	Update URL, label, or expiry
disable(id)	Stop redirecting
enable(id)	Resume redirecting
delete(id)	Permanently delete
analytics(id, *, range=None)	Click breakdown by country, device, referrer, etc.
timeline(id, *, range=None)	Click counts bucketed over time
qr(id, *, slug=None, size=None)	QR code as SVG string
bundles(id)	Bundles this link belongs to

# Shorten a URL
link = client.links.create(url="https://example.com", label="Landing page")

# Get a 7-day click count
fresh = client.links.get(link.id, range="7d")

# Full analytics for the last 30 days
stats = client.links.analytics(link.id, range="30d")
print(stats.total_clicks, stats.countries, stats.browsers)

Slugs (client.slugs)

Method	Description
lookup(slug)	Find a link by slug
add(link_id, slug)	Add a custom slug
disable(link_id, slug)	Disable a slug
enable(link_id, slug)	Re-enable a slug
remove(link_id, slug)	Remove a slug

# Add a campaign slug then disable it when the campaign ends
client.slugs.add(link.id, "spring-sale")
client.slugs.disable(link.id, "spring-sale")

# Look up a link by its slug
found = client.slugs.lookup("spring-sale")

Bundles (client.bundles)

Groups of related links with combined analytics.

Method	Description
get(id, *, range=None)	Get a bundle with click summary
list(*, archived=None, range=None)	List bundles
create(*, name, description=None, icon=None, accent=None)	Create a bundle
update(id, *, name=None, description=None, icon=None, accent=None)	Update metadata
delete(id)	Permanently delete
archive(id)	Hide from default listing
unarchive(id)	Restore an archived bundle
analytics(id, *, range=None)	Combined click analytics
links(id)	List links in the bundle
add_link(id, link_id)	Add a link
remove_link(id, link_id)	Remove a link

# Create a bundle and add links to it
bundle = client.bundles.create(name="Spring 2026", accent="green")
client.bundles.add_link(bundle.id, link_a.id)
client.bundles.add_link(bundle.id, link_b.id)

# Combined analytics for the last 7 days
stats = client.bundles.analytics(bundle.id, range="7d")
print(stats.total_clicks)

Models

All model fields use snake_case, matching the wire format. Types are frozen dataclasses.

Key types exported from shrtnr:

• Link, Slug, Bundle, BundleWithSummary
• ClickStats, TimelineData, NameCount, TimelineBucket, TimelineSummary
• DeletedResult, AddedResult, RemovedResult
• TimelineRange (Literal["24h", "7d", "30d", "90d", "1y", "all"])
• BundleAccent (Literal["orange", "red", "green", "blue", "purple"])

Errors

Every 4xx/5xx response raises ShrtnrError. Network failures also raise ShrtnrError with status=0.

from shrtnr import ShrtnrError

try:
    client.links.get(99999)
except ShrtnrError as err:
    print(err.status)         # 404
    print(err.server_message) # "not found"
    print(str(err))           # "shrtnr API error (HTTP 404): not found"

Migrating from 0.x

1.0 is a clean break. Summary of changes:

Resource-grouped client. Methods moved to namespaces.

# 0.x
client.create_link(CreateLinkOptions(url="..."))
client.add_custom_slug(link_id, "promo")
client.archive_bundle(bundle_id)

# 1.0
client.links.create(url="...")
client.slugs.add(link_id, "promo")
client.bundles.archive(bundle_id)

Constructor shape changed. base_url is now keyword-only.

# 0.x
Shrtnr("https://...", api_key="sk_...")

# 1.0
Shrtnr(base_url="https://...", api_key="sk_...")

ShrtnrError shape changed. The body field is gone; use server_message.

# 0.x
err.body          # raw parsed JSON body

# 1.0
err.server_message  # the "error" string from the response

Result types. delete, add_link, and remove_link return typed dataclasses instead of bool.

# 0.x
if client.delete_link(id):  # bool

# 1.0
result = client.links.delete(id)
if result.deleted:  # DeletedResult.deleted

ClickStats expanded. New fields: referrer_hosts, link_modes, channels, num_countries, num_referrers, num_referrer_hosts, num_os, num_browsers.

BundleWithSummary is flat. Fields are directly on the object instead of nested under a bundle attribute.

bundles.list archived parameter is now a string enum ("all", "only", "1", "true") instead of a Python bool.

health() removed. The /_/health endpoint is outside the public API spec.

See also

• API docs: /_/api/docs on your shrtnr deployment
• OpenAPI spec: /_/api/openapi.json
• Source: github.com/oddbit/shrtnr

License

Apache 2.0. Built and maintained by Oddbit.