linkbreakers

Official Python SDK for the Linkbreakers API.

Installation

pip install linkbreakers

Usage

from linkbreakers import Configuration, ApiClient, LinksApi

# Configure API client with Bearer token authentication
configuration = Configuration(
    access_token='your-api-token',
    host='https://api.linkbreakers.com'
)

# Create API client
with ApiClient(configuration) as api_client:
    links_api = LinksApi(api_client)

    # Create a shortened link
    link = links_api.create_link({
        'destination': 'https://example.com',
        'name': 'My Link'
    })

    print(f'Short link: {link.shortlink}')

Authentication

Important: The Linkbreakers API uses Bearer token authentication. The SDK's Configuration class is designed to only accept the access_token parameter:

# ✅ CORRECT - Uses Bearer token authentication
configuration = Configuration(
    access_token='your-workspace-token',
    host='https://api.linkbreakers.com'
)

# ❌ ERROR - Will raise ValueError
configuration = Configuration(
    api_key={'ApiKeyAuth': 'your-token'}  # This will raise an error!
)

The SDK prevents you from accidentally using the wrong authentication method and will raise a clear error message with a link to the help documentation.

Get your workspace API token from the Linkbreakers dashboard.

For more information, see: https://linkbreakers.com/help/article/api-authentication-accesstoken-vs-apikey

Identifying Visitors

Use the VisitorsApi to identify and update visitor profiles. The identify method finds or creates a visitor using their LBID (from tracking) and merges attributes:

from linkbreakers import (
    Configuration,
    ApiClient,
    VisitorsApi,
    IdentifyRequest,
    VisitorInput
)

configuration = Configuration(
    access_token='your-api-token',
    host='https://api.linkbreakers.com'
)

with ApiClient(configuration) as api_client:
    visitors_api = VisitorsApi(api_client)

    # Identify a visitor using their LBID (from tracking cookie/parameter)
    response = visitors_api.visitors_service_identify(
        identify_request=IdentifyRequest(
            lbid='visitor-lbid-from-tracking',  # Base64 encoded event ID from click/scan
            visitor=VisitorInput(
                data={
                    # System fields (prefixed with "$")
                    '$email': 'user@example.com',
                    '$phone': '+1234567890',
                    '$firstName': 'John',
                    '$lastName': 'Doe',

                    # Custom attributes (no "$" prefix)
                    'company': 'Acme Corp',
                    'plan': 'premium',
                    'signupDate': '2024-01-01'
                }
            ),
            set_once=False  # If True, only sets empty fields (won't overwrite existing)
        )
    )

    print(f'Created new profile: {response.created}')
    print(f'Visitor: {response.visitor}')

Update an existing visitor by UUID:

from linkbreakers import VisitorsServiceUpdateBody, VisitorInput

with ApiClient(configuration) as api_client:
    visitors_api = VisitorsApi(api_client)

    # When you have the visitor's UUID (from your database)
    visitor = visitors_api.visitors_service_update(
        id='visitor-uuid',
        visitors_service_update_body=VisitorsServiceUpdateBody(
            visitor=VisitorInput(
                data={
                    '$email': 'updated@example.com',
                    'plan': 'enterprise'
                }
            )
        )
    )

Get visitor details:

with ApiClient(configuration) as api_client:
    visitors_api = VisitorsApi(api_client)

    visitor = visitors_api.visitors_service_get(
        id='visitor-uuid',
        include=['devices', 'events', 'links']  # Optional: include related data
    )

List visitors:

with ApiClient(configuration) as api_client:
    visitors_api = VisitorsApi(api_client)

    visitors = visitors_api.visitors_service_list(
        page_size=50,
        email='user@example.com',  # Optional filters
        link_id='link-uuid',
        search='Acme Corp'
    )

Full API Support

The SDK provides type-safe methods for all API operations:

from linkbreakers import Configuration, ApiClient, LinksApi

configuration = Configuration(
    access_token='your-api-token',
    host='https://api.linkbreakers.com'
)

with ApiClient(configuration) as api_client:
    links_api = LinksApi(api_client)

    # Get a link by ID
    link = links_api.get_link(id='link-id')

    # Update a link
    updated = links_api.update_link(
        id='link-id',
        update_link_request={
            'name': 'Updated Name'
        }
    )

    # Delete a link
    links_api.delete_link(id='link-id')

    # List links with filtering
    links = links_api.list_links(
        page_size=50,
        search='my-search',
        tags=['tag1', 'tag2']
    )

Features

✅ Full type hints and autocompletion support
✅ Python 3.7+ support
✅ Auto-generated from OpenAPI specification
✅ Automatically updated when API changes

Examples

For complete, runnable code examples, see the examples/ directory:

identify_visitor.py - Identify visitors using LBID (most important!)
update_visitor.py - Update visitors by UUID
create_link.py - Create shortened links with various options
list_visitors.py - Query and filter visitors

Each example is complete, well-documented, and ready to run. See examples/README.md for details.

Documentation

For complete API documentation, visit https://docs.linkbreakers.com

Auto-Generated SDK

This SDK is automatically generated from the Linkbreakers OpenAPI specification. When the API is updated, this SDK is automatically regenerated and published.

Current API Version: See OPENAPI_VERSION

Support

Issues: GitHub Issues
Documentation: https://docs.linkbreakers.com

License

MIT License - see LICENSE for details.

Metadata

Release files for linkbreakers 1.125.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for linkbreakers 1.125.0
File	Size	Uploaded
linkbreakers-1.125.0.tar.gz	200.6 kB	Sep 20, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for linkbreakers 1.125.0
File	Interpreter	ABI	Platform	Reset
linkbreakers-1.125.0-py3-none-any.whl 661.7 kB Sep 20, 2026	Python 3	none	any	Details

Total release size: 862.3 kB

Release files / linkbreakers-1.125.0.tar.gz

Download URL	linkbreakers-1.125.0.tar.gz
Size	200.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`92bf342055d583d608fdd95f2dc74e11ceefaeeb02048e9c1576e0fcabed88bd`
BLAKE2b-256 checksum How to use checksums	`c06ea83bdc24c2fcb5b61d58c3af237f54f390fa1027f7db7f6665cf1dbc122d`
Upload date	Sep 20, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.11.16`

Release files / linkbreakers-1.125.0-py3-none-any.whl

Download URL	linkbreakers-1.125.0-py3-none-any.whl
Size	661.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`1e00a1ac9998c61823aba4ad13a64e4b48fdb2a15d3931f815ee0a217d12ed9d`
BLAKE2b-256 checksum How to use checksums	`d1f156629e91398bf8832e14a12f5762d4a068e73e2fc61531a380e5e88ee576`
Upload date	Sep 20, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.11.16`