A Python client library for the Short.io API, auto-generated from the OpenAPI specification using openapi-python-client.
- Python 3.10+
- httpx >= 0.23.0
pip install short-io-api-clientpoetry add short-io-api-clientAll 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>"
)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)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)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)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)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)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)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())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 bytesEnable 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")| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
import httpx
client = AuthenticatedClient(
base_url="https://api.short.io",
token="YOUR_API_KEY",
prefix="",
timeout=httpx.Timeout(30.0),
)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}")],
}
},
)client = AuthenticatedClient(
base_url="https://api.short.io",
token="YOUR_API_KEY",
prefix="",
verify_ssl="/path/to/certificate_bundle.pem",
)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 |
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