shotcut-python 1.0.1

Python client for the Shotcut.in URL shortener API

Shotcut Python API Client

A comprehensive Python client for the Shotcut.in URL shortener API. This package provides an intuitive interface to interact with all Shotcut.in API endpoints.

Get Your API Key Here

Table of Contents

• Installation
• Features
• Quick Start
• API Reference
  • Account Management
  • URL Shortening
  • QR Codes
  • Campaigns
  • Branded Domains
  • Channels
  • Pixels
  • Custom Splash Pages
  • CTA Overlays
• Error Handling
• Development
• License

Installation

pip install shotcut-python

Features

• URL Shortening: Create and manage shortened URLs with custom aliases
• QR Code Generation: Create customizable QR codes with logos and colors
• Campaign Management: Organize and track marketing campaigns
• Branded Domains: Set up and manage custom domains
• Channels: Organize content into channels with custom settings
• Pixels: Implement tracking pixels for analytics
• Custom Splash Pages: Create and manage intermediate pages
• CTA Overlays: Add call-to-action overlays to links
• Error Handling: Built-in handling for API errors and rate limits
• Type Hints: Full typing support for better IDE integration

Quick Start

from shotcut import ShotcutAPI

# Initialize the client
api = ShotcutAPI(api_key="your_api_key_here")

# Shorten a URL
response = api.shorten_link(
    url="https://example.com",
    custom="my-custom-alias"
)
print(response['shorturl'])

# Create a QR code
qr = api.create_qr_code(
    type="link",
    data="https://example.com",
    background="rgb(255,255,255)",
    foreground="rgb(0,0,0)"
)
print(qr['link'])

API Reference

Account Management

# Get account information
account = api.get_account()

# Update account details
api.update_account(
    email="[e-mail]",
    password="newpassword123"
)

URL Shortening

# Create a shortened URL
url = api.shorten_link(
    url="https://example.com",
    custom="my-link",
    password="secret123",
    expiry="2025-12-31",
    domain="custom.com"
)

# List all URLs
urls = api.list_links(
    limit=20,
    page=1,
    order="clicks"
)

# Get single URL details
url_details = api.get_link(link_id=123)

# Update URL
api.update_link(
    link_id=123,
    url="https://newexample.com",
    password="newpassword123"
)

# Delete URL
api.delete_link(link_id=123)

QR Codes

# Create QR code
qr = api.create_qr_code(
    type="link",
    data="https://example.com",
    background="rgb(255,255,255)",
    foreground="rgb(0,0,0)",
    logo="https://example.com/logo.png"
)

# List QR codes
qr_codes = api.list_qr_codes(limit=20, page=1)

# Get single QR code
qr_details = api.get_qr_code(qr_id=123)

# Update QR code
api.update_qr_code(
    qr_id=123,
    data="https://newexample.com",
    background="rgb(0,0,255)"
)

# Delete QR code
api.delete_qr_code(qr_id=123)

Campaigns

# Create campaign
campaign = api.create_campaign(
    name="Summer Sale 2025",
    slug="summer-sale",
    public=True
)

# List campaigns
campaigns = api.list_campaigns(limit=20, page=1)

# Assign link to campaign
api.assign_link_to_campaign(
    campaign_id=123,
    link_id=456
)

# Update campaign
api.update_campaign(
    campaign_id=123,
    name="Winter Sale 2025",
    public=False
)

# Delete campaign
api.delete_campaign(campaign_id=123)

Branded Domains

# List domains
domains = api.list_domains(limit=20, page=1)

# Create domain
domain = api.create_domain(
    domain="short.example.com",
    redirect_root="https://example.com",
    redirect_404="https://example.com/404"
)

# Update domain
api.update_domain(
    domain_id=123,
    redirect_root="https://newexample.com"
)

# Delete domain
api.delete_domain(domain_id=123)

Channels

# Create channel
channel = api.create_channel(
    name="Marketing",
    description="Marketing campaign links",
    color="rgb(255,0,0)",
    starred=True
)

# List channels
channels = api.list_channels(limit=20, page=1)

# List channel items
items = api.list_channel_items(
    channel_id=123,
    limit=20,
    page=1
)

# Update channel
api.update_channel(
    channel_id=123,
    name="Sales",
    starred=False
)

# Delete channel
api.delete_channel(channel_id=123)

Pixels

# Create pixel
pixel = api.create_pixel(
    type="facebook",
    name="FB Conversion Pixel",
    tag="123456789"
)

# List pixels
pixels = api.list_pixels(limit=20, page=1)

# Update pixel
api.update_pixel(
    pixel_id=123,
    name="Updated FB Pixel",
    tag="987654321"
)

# Delete pixel
api.delete_pixel(pixel_id=123)

Custom Splash Pages

# List splash pages
splash_pages = api.list_splash(limit=20, page=1)

CTA Overlays

# List overlays
overlays = api.list_overlays(limit=20, page=1)

Error Handling

from shotcut import ShotcutAPI, ShotcutAPIError

try:
    api = ShotcutAPI(api_key="your_key")
    response = api.create_link(url="https://example.com")
except ShotcutAPIError as e:
    print(f"API Error: {str(e)}")
except RateLimitError as e:
    print(f"Rate limit exceeded. Reset at {e.reset_time}")
except AuthenticationError as e:
    print("Invalid API key")
except ValidationError as e:
    print(f"Invalid data: {str(e)}")

Development

To contribute to this project:

1. Clone the repository

git clone https://github.com/Shotcut-Track/shotcutapi-python.git

2. Install development dependencies

pip install -e ".[dev]"

3. Run tests

pytest

License

MIT License - see LICENSE file for details.