Logo of linkbreakers

Linkbreakers Python SDK: Complete Integration Guide

Learn how to integrate the Linkbreakers Python SDK in your application for programmatic link management, QR code generation, and analytics. Includes installation, authentication, and code examples.

Developer
2 min read
By Laurent Schaffner
Updated March 20, 2025

Short answer

The Linkbreakers Python SDK enables programmatic link management, QR code generation, and analytics access from your Python applications. Install it with pip install linkbreakers-python and authenticate using a secret API key from your dashboard to start creating and managing links.

Installation

Install the SDK using pip:

Bash 
pip install linkbreakers-python

For Poetry users:

Bash 
poetry add linkbreakers-python

Creating a secret API key

Before using the SDK, create a secret API key:

  1. Log in to app.linkbreakers.com
  2. Navigate to Dashboard → API Tokens
  3. Click Create API Token
  4. Select Secret Key as the key type
  5. Copy the generated key (starts with sk_live_...)

Important: Secret keys provide full access to your workspace. Never commit them to version control or expose them in public repositories. Store them in environment variables or secret management systems.

Quick start

Initialize the client and create your first shortened link:

Python 
from linkbreakers import LinkbreakersClient

# Initialize with your secret key
client = LinkbreakersClient(api_key='sk_live_...')

# Create a shortened link
link = client.links.create(
    destination='https://example.com/product',
    name='Product Page - Spring Campaign',
    tags=['marketing', 'spring-2025']
)

print(f"Short URL: {link.shortlink}")
print(f"QR Code: {link.qrcode_signed_url}")

Creating links with custom options

Customize your links with domains, shortlinks, and workflow steps:

Python 
# Create a link with a custom shortlink
link = client.links.create(
    destination='https://example.com/docs',
    shortlink='docs',  # Creates lbr.ai/docs
    name='Documentation Home',
    fallback_destination='https://example.com/404'
)

# Use a custom domain (must be configured in dashboard)
link = client.links.create(
    destination='https://example.com/signup',
    custom_domain_id='123e4567-e89b-12d3-a456-426614174000',
    name='Signup Landing Page'
)

# Create with metadata for tracking
link = client.links.create(
    destination='https://example.com/offer',
    metadata={
        'campaign_id': 'summer-sale-2025',
        'utm_source': 'email',
        'customer_segment': 'premium'
    }
)

Managing links

List, retrieve, update, and delete links programmatically:

Python 
# List all links with filtering
links = client.links.list(
    page_size=50,
    tags=['marketing'],
    search='campaign'
)

for link in links.links:
    print(f"{link.name}: {link.shortlink}")

# Get a specific link by ID
link = client.links.get(
    id='123e4567-e89b-12d3-a456-426614174000',
    include=['tags', 'qrcodeSignedUrl']
)

# Update a link
client.links.update(
    id=link.id,
    name='Updated Campaign Name',
    tags=['marketing', 'q2-2025']
)

# Delete a link
client.links.delete(id=link.id)

Working with QR codes

Generate and customize QR codes for your links:

Python 
# Create a QR code design
qr_design = client.qrcode_designs.create(
    dots_options={
        'type': 'rounded',
        'theme_color': {
            'type': 'THEME_COLOR_TYPE_SOLID',
            'colors': ['#FF6B6B']
        }
    },
    corners_square_options={
        'type': 'extra-rounded',
        'theme_color': {
            'type': 'THEME_COLOR_TYPE_SOLID',
            'colors': ['#1E3A8A']
        }
    },
    width=1000,
    height=1000,
    output_file_format='OUTPUT_FILE_FORMAT_PNG'
)

# Create a link with the custom QR code design
link = client.links.create(
    destination='https://example.com/event',
    qrcode_design_id=qr_design.id,
    wait_for_qrcode=True  # Wait for QR generation before returning
)

print(f"QR Code URL: {link.qrcode_signed_url}")

Accessing analytics

Retrieve visitor events and link performance data:

Python 
from datetime import datetime, timedelta

# Get events for a specific link
end_date = datetime.now()
start_date = end_date - timedelta(days=30)

events = client.events.list(
    link_id='123e4567-e89b-12d3-a456-426614174000',
    start_date=start_date.isoformat(),
    end_date=end_date.isoformat(),
    page_size=100,
    include=['visitor', 'device', 'link']
)

for event in events.events:
    print(f"{event.action} - {event.visitor.email} - {event.created_at}")

# Get workspace metrics
metrics = client.metrics.workspace()
print(f"Total links: {metrics.total_links}")
print(f"Total clicks: {metrics.total_clicks}")

Environment variables

Store your API key in environment variables for security:

Python 
import os
from linkbreakers import LinkbreakersClient

# Read from environment variable
client = LinkbreakersClient(
    api_key=os.getenv('LINKBREAKERS_API_KEY')
)

In your .env file:

Bash 
LINKBREAKERS_API_KEY=sk_live_your_secret_key_here

Frequently asked questions

Can I use the Python SDK in Django or Flask applications?

Yes, the SDK is framework-agnostic and works with any Python application including Django, Flask, FastAPI, and serverless functions.

How do I handle rate limits?

The SDK automatically handles rate limits. If you exceed limits, it will raise an exception. Implement retry logic with exponential backoff for production applications.

Can I create bulk links?

Yes, use the client.links.create_bulk() method to create multiple links in a single API call, which is more efficient than individual calls.

Is async/await supported?

The current version uses synchronous HTTP calls. For async applications, consider running SDK calls in a thread pool executor or using asyncio.to_thread().

How do I test without affecting production data?

Create test mode API keys (prefixed with sk_test_) from your dashboard. Test keys operate on isolated test data that doesn't affect production analytics.

Sources

Last reviewed

This article was last reviewed on March 20, 2025.

About the Author

LS

Laurent Schaffner

Founder & Engineer at Linkbreakers

Passionate about building tools that help businesses track and optimize their digital marketing efforts. Laurent founded Linkbreakers to make QR code analytics accessible and actionable for companies of all sizes.

Related Articles

How to use the Linkbreakers API

Complete guide to integrating with the Linkbreakers API - create QR codes, manage links, customize designs, track analytics, and automate workflows programmatically.

Analytics API

Access comprehensive QR code and visitor analytics through the Linkbreakers API. Learn how to retrieve campaign performance data, visitor insights, and engagement metrics programmatically for business intelligence integration.

How to integrate Linkbreakers with existing tech stack

Integrate Linkbreakers with your CRM, marketing automation, analytics platforms, and business systems through APIs, webhooks, and direct integrations. Learn best practices for seamless tech stack integration.

Back to Help Center