short-io-api-client

A Python client library for the Short.io API, auto-generated from the OpenAPI specification using openapi-python-client.

Requirements

• Python 3.10+
• httpx >= 0.23.0

Installation

Using Poetry

poetry add /path/to/short-io-api-client

Using pip (from wheel)

cd short-io-api-client
poetry build -f wheel
pip install dist/short_io_api_client-1.0.0-py3-none-any.whl

Quick Start

Authentication

All Short.io API endpoints require an API key. Create an AuthenticatedClient with your key passed via the Authorization header:

from short_io_api_client import AuthenticatedClient

client = AuthenticatedClient(
    base_url="https://api.short.io",
    token="YOUR_API_KEY",
    prefix="",  # Short.io uses a raw API key, not "Bearer <token>"
)

Create a Short Link

from short_io_api_client import AuthenticatedClient
from short_io_api_client.api.link_management import post_links
from short_io_api_client.models import PostLinksBody

client = AuthenticatedClient(
    base_url="https://api.short.io",
    token="YOUR_API_KEY",
    prefix="",
)

with client as c:
    result = post_links.sync(
        client=c,
        body=PostLinksBody(
            original_url="https://example.com/my-long-url",
            domain="your-domain.short.gy",
            path="my-custom-slug",
            title="My Link",
            tags=["marketing", "campaign"],
        ),
    )
    print(result)

List Domains

from short_io_api_client.api.domains import get_api_domains

with client as c:
    domains = get_api_domains.sync(client=c)
    if domains:
        for domain in domains:
            print(domain)

List Links for a Domain

from short_io_api_client.api.link_queries import get_api_links

with client as c:
    result = get_api_links.sync(client=c, domain_id=123456)
    print(result)

Update a Link

from short_io_api_client.api.link_management import post_links_link_id
from short_io_api_client.models import PostLinksLinkIdBody

with client as c:
    result = post_links_link_id.sync(
        link_id="lnk_abc123",
        client=c,
        body=PostLinksLinkIdBody(
            original_url="https://example.com/updated-url",
            title="Updated Title",
        ),
    )
    print(result)

Delete a Link

from short_io_api_client.api.link_management import delete_links_link_id

with client as c:
    result = delete_links_link_id.sync(link_id="lnk_abc123", client=c)
    print(result)

Get Link by Original URL

from short_io_api_client.api.link_queries import get_links_by_original_url

with client as c:
    result = get_links_by_original_url.sync(
        client=c,
        domain="your-domain.short.gy",
        original_url="https://example.com/my-long-url",
    )
    print(result)

Async Usage

Every endpoint has async variants. Replace .sync() with .asyncio():

import asyncio
from short_io_api_client import AuthenticatedClient
from short_io_api_client.api.link_management import post_links
from short_io_api_client.models import PostLinksBody

client = AuthenticatedClient(
    base_url="https://api.short.io",
    token="YOUR_API_KEY",
    prefix="",
)

async def main():
    async with client as c:
        result = await post_links.asyncio(
            client=c,
            body=PostLinksBody(
                original_url="https://example.com",
                domain="your-domain.short.gy",
            ),
        )
        print(result)

asyncio.run(main())

Detailed Responses

Use the _detailed variants to get full HTTP response information:

from short_io_api_client.api.link_management import post_links
from short_io_api_client.types import Response

with client as c:
    response: Response = post_links.sync_detailed(
        client=c,
        body=PostLinksBody(
            original_url="https://example.com",
            domain="your-domain.short.gy",
        ),
    )
    print(response.status_code)  # HTTPStatus enum
    print(response.headers)      # dict
    print(response.parsed)       # parsed model or None
    print(response.content)      # raw bytes

Error Handling

Enable raise_on_unexpected_status to raise on undocumented status codes:

client = AuthenticatedClient(
    base_url="https://api.short.io",
    token="YOUR_API_KEY",
    prefix="",
    raise_on_unexpected_status=True,
)

Documented error responses (400, 401, 402, 403, 404, 409, 500) are returned as typed model objects. Check the response type to handle errors:

from short_io_api_client.models import PostLinksResponse200, PostLinksResponse409

result = post_links.sync(client=c, body=body)

if isinstance(result, PostLinksResponse200):
    print("Created:", result)
elif isinstance(result, PostLinksResponse409):
    print("Conflict: link path already exists")

API Modules

Module	Description
api.link_management	Create, update, delete, archive, bulk operations, QR codes, permissions
api.link_queries	List links, get by ID/URL, folders, OpenGraph data
api.link_targeting	Country and region-based link targeting
api.domains	List, get, create, and configure domains

Link Management Endpoints

Function	Description
post_links	Create a new short link
post_links_link_id	Update a link by ID
delete_links_link_id	Delete a link by ID
delete_links_delete_bulk	Bulk delete links
post_links_bulk	Bulk create links
post_links_archive	Archive a link
post_links_unarchive	Unarchive a link
post_links_archive_bulk	Bulk archive links
post_links_unarchive_bulk	Bulk unarchive links
post_links_duplicate_link_id	Duplicate a link
post_links_qr_link_id_string	Generate QR code for a link
post_links_qr_bulk	Bulk generate QR codes
post_links_public	Create a public link
post_links_examples	Get link examples
post_tags_bulk	Bulk tag operations
put_links_opengraph_domain_id_link_id	Update OpenGraph data
get_links_permissions_domain_id_link_id	Get link permissions
post_links_permissions_domain_id_link_id_user_id	Set link permissions
delete_links_permissions_domain_id_link_id_user_id	Remove link permissions
get_links_tweetbot	Tweetbot integration

Link Query Endpoints

Function	Description
get_api_links	List links for a domain
get_links_link_id	Get link by ID
get_links_by_original_url	Get link by original URL
get_links_expand	Expand a short link
get_links_multiple_by_url	Get multiple links by URL
get_links_opengraph_domain_id_link_id	Get OpenGraph data
get_links_folders_domain_id	List folders for a domain
get_links_folders_domain_id_folder_id	Get folder by ID
post_links_folders	Create a folder

Domain Endpoints

Function	Description
get_api_domains	List all domains
get_domains_domain_id	Get domain by ID
post_domains	Create a new domain
post_domains_settings_domain_id	Update domain settings

Link Targeting Endpoints

Function	Description
get_link_country_link_id	Get country targeting rules
post_link_country_link_id	Set country targeting
post_link_country_bulk_link_id	Bulk set country targeting
delete_link_country_link_id_country	Delete country targeting rule
get_link_region_link_id	Get region targeting rules
post_link_region_link_id	Set region targeting
post_link_region_bulk_link_id	Bulk set region targeting
delete_link_region_link_id_country_region	Delete region targeting rule
get_link_region_list_country	List regions for a country

Advanced Configuration

Custom Timeout

import httpx

client = AuthenticatedClient(
    base_url="https://api.short.io",
    token="YOUR_API_KEY",
    prefix="",
    timeout=httpx.Timeout(30.0),
)

Request/Response Logging

client = AuthenticatedClient(
    base_url="https://api.short.io",
    token="YOUR_API_KEY",
    prefix="",
    httpx_args={
        "event_hooks": {
            "request": [lambda r: print(f"-> {r.method} {r.url}")],
            "response": [lambda r: print(f"<- {r.status_code}")],
        }
    },
)

Custom SSL Certificate

client = AuthenticatedClient(
    base_url="https://api.short.io",
    token="YOUR_API_KEY",
    prefix="",
    verify_ssl="/path/to/certificate_bundle.pem",
)

Function Variants

Every endpoint module provides four functions:

Function	Description
sync	Blocking call, returns parsed response model or None
sync_detailed	Blocking call, returns Response with status, headers, and parsed body
asyncio	Async call, returns parsed response model or None
asyncio_detailed	Async call, returns Response with status, headers, and parsed body

Building / Publishing

This project uses Poetry for dependency management and packaging:

# Build a wheel
poetry build -f wheel

# Publish to PyPI
poetry publish --build

# Publish to a private repository
poetry config repositories.my-repo https://my-repo.example.com/simple/
poetry publish --build -r my-repo