LinkVice Python SDK

Official Python client library for the LinkVice redirect-management API.

Installation

pip install linkvice

Or install from source:

git clone https://github.com/linkvice/linkvice-python.git
cd linkvice-python
pip install .

Quick Start

from linkvice import LinkVice

client = LinkVice(api_key="your-api-key")

# List all domains
domains = client.get_domains()
print(domains)

Authentication

Every request requires a valid API key passed as a Bearer token. Obtain your key from the LinkVice dashboard.

client = LinkVice(
    api_key="your-api-key",
    base_url="https://www.linkvice.com/api/v1/",  # default
    timeout=30,                                      # seconds, default
)

Usage

Domains

# List all domains
domains = client.get_domains()

# Add a domain
new_domain = client.add_domain("example.com", use_ssl=True)

# Get a single domain
domain = client.get_domain(domain_id=1)

# Delete a domain
client.delete_domain(domain_id=1)

Redirects

# List redirects (with optional filters)
redirects = client.get_redirects(domain_id=1, page=1, per_page=25)

# Create a redirect
redirect = client.create_redirect(
    domain_id=1,
    target_url="https://destination.example.com",
    redirect_type="permanent",
    http_code=301,
)

# Create a redirect with advanced options
redirect = client.create_redirect(
    domain_id=1,
    target_url="https://destination.example.com",
    http_code=302,
    block_bots=True,
    language_rules=[
        {"language": "de", "target_url": "https://example.de"},
        {"language": "fr", "target_url": "https://example.fr"},
    ],
    image_redirect_url="https://cdn.example.com/og.png",
    favicon_redirect="https://cdn.example.com/favicon.ico",
    robots_redirect="https://example.com/robots.txt",
    ads_redirect="https://example.com/ads.txt",
    llm_redirect="https://example.com/llms.txt",
)

# Get a single redirect
redirect = client.get_redirect(redirect_id=42)

# Update a redirect
updated = client.update_redirect(redirect_id=42, target_url="https://new-target.com")

# Delete a redirect
client.delete_redirect(redirect_id=42)

Statistics

# Redirect-level stats
stats = client.get_redirect_stats(
    redirect_id=42,
    date_from="2025-01-01",
    date_to="2025-12-31",
    country="US",
    language="en",
)

# Domain-level stats
stats = client.get_domain_stats(
    domain_id=1,
    date_from="2025-01-01",
    date_to="2025-12-31",
)

Blacklist

# List all blacklist rules
rules = client.get_blacklist_rules()

# List rules by type
ip_rules = client.get_blacklist_rules(rule_type="ip")

# Add a plain-string rule
rule = client.add_blacklist_rule(
    rule_type="ip",
    pattern="192.168.1.100",
    note="Block office test machine",
)

# Add a regex rule
rule = client.add_blacklist_rule(
    rule_type="user_agent",
    pattern=r".*BadBot.*",
    is_regex=True,
    note="Block BadBot crawler",
)

# Delete a rule
client.delete_blacklist_rule(rule_id=5)

Error Handling

The SDK raises typed exceptions for different error scenarios:

from linkvice import (
    LinkVice,
    LinkViceError,
    AuthenticationError,
    NotFoundError,
    RateLimitError,
    ValidationError,
)

client = LinkVice(api_key="your-api-key")

try:
    client.get_domain(999)
except AuthenticationError:
    print("Invalid API key")
except NotFoundError:
    print("Domain not found")
except RateLimitError:
    print("Too many requests -- slow down")
except ValidationError as exc:
    print(f"Bad request: {exc.message}")
except LinkViceError as exc:
    print(f"Unexpected API error: {exc.message} (HTTP {exc.status_code})")

Exception	HTTP Status	Description
AuthenticationError	401, 403	Invalid or missing API key
NotFoundError	404	Resource does not exist
RateLimitError	429	Rate limit exceeded
ValidationError	400, 422	Invalid request data
LinkViceError	Any other	Base class for all SDK errors

Context Manager

The client can be used as a context manager to ensure the underlying HTTP session is properly closed:

with LinkVice(api_key="your-api-key") as client:
    domains = client.get_domains()

Requirements

• Python 3.10+
• requests >= 2.28.0

License

MIT -- see LICENSE for details.