linkbreakers

Official Python SDK for the Linkbreakers API.

Installation

pip install linkbreakers

Usage

from linkbreakers import Configuration, ApiClient, LinksApi, CreateLinkRequest

# 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
    response = links_api.links_service_create(
        create_link_request=CreateLinkRequest(
            destination='https://example.com',
            name='My Link'
        )
    )

    print(f'Short link: {response.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. Method names follow the API's operation IDs (links_service_create, links_service_list, visitors_service_identify, ...), and request bodies are passed as the keyword named after their model (create_link_request, links_service_update_body, ...):

from linkbreakers import Configuration, ApiClient, LinksApi, LinksServiceUpdateBody

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.links_service_get(id='link-id').link

    # Update a link
    updated = links_api.links_service_update(
        id='link-id',
        links_service_update_body=LinksServiceUpdateBody(
            name='Updated Name'
        )
    )

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

    # List links with filtering
    links = links_api.links_service_list(
        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.164.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.164.0
File	Size	Uploaded
linkbreakers-1.164.0.tar.gz	320.6 kB	Oct 10, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for linkbreakers 1.164.0
File	Interpreter	ABI	Platform	Reset
linkbreakers-1.164.0-py3-none-any.whl 1.6 MB Oct 10, 2026	Python 3	none	any	Details

Total release size: 1.9 MB

Release files / linkbreakers-1.164.0.tar.gz

Download URL	linkbreakers-1.164.0.tar.gz
Size	320.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`0ad381c5b3f3ce721af58c8fef54697f694d9a59c1ab3b9414ad60a10d3b110c`
BLAKE2b-256 checksum How to use checksums	`3fa8cde00c7032302b240c3287bd02d9040491cb4933e4eb24c9b39d21025be6`
Upload date	Oct 10, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.11.17`

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

Download URL	linkbreakers-1.164.0-py3-none-any.whl
Size	1.6 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`227dcba09e3833e5dfd35108522a208aadcda0b4d13c274f7bab8096120ed60f`
BLAKE2b-256 checksum How to use checksums	`8bf4901cea4c6e7bf3a53f6ee223c09ad7a8b9edd939da23362c6e44f62a356e`
Upload date	Oct 10, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.11.17`