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:

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 takes the same parameters, with 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)

# 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)

# 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.

# 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)

Config (client.config)

Deployment settings a client needs to build short URLs.

# Matches the copy button and QR code: primary slug, else first custom, else generated.
# link.short_origin works on deployments that predate config.get().
primary = (
    next((s for s in link.slugs if s.is_primary), None)
    or next((s for s in link.slugs if s.is_custom), None)
    or link.slugs[0]
)
short_url = f"{link.short_origin}/{primary.slug}"

Models

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

Every Link carries short_origin: the origin this deployment hands short URLs out on. It is the deployment's SHORT_ORIGIN when set, otherwise the request origin. client.config.get() returns the same value. Build short URLs as f"{short_origin}/{slug}" so they match the copy button, the QR code and the redirects. Deployments older than the field omit it, so the SDK fills in the origin of base_url.

Key types exported from shrtnr:

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

Errors

Any 4xx/5xx response or network failure raises ShrtnrError. A network failure carries 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"

See also

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

Attribution

shrtnr is developed and maintained by Oddbit.

• Source repository: https://github.com/oddbit/shrtnr
• License: Apache License 2.0
• Attribution notices: NOTICE
• Name and logo usage: Trademark Policy

If you publish a fork or derivative work, retain the license and notice files, preserve applicable copyright and attribution notices, and clearly indicate that your version has been modified.