Python SDK

subdomainto v0.1 supports Python 3.9 and later and uses httpx. It is a server-side client for all 12 core API operations.

Installation

BASH
pip install subdomainto

Initialize the client

PYTHON
import os
from subdomainto import SubdomainTo

client = SubdomainTo(os.environ["SUBDOMAINTO_API_KEY"])

You may pass a custom base_url or httpx.Client. Use the client as a context manager, or call close() when you are finished.

Create a domain

PYTHON
domain = client.domains.create("portal.customer.com", "customer-42-domain", destination_id=destination_id)

Creation methods require a stable 1–128 character idempotency key. The SDK performs no implicit retries.

Resources

The client exposes destinations.list/create, domains.list/create/get/delete, webhooks.create, widget.create_session, usage.get, and health().

Handle errors

PYTHON
from subdomainto import ConflictError, SubdomainToError, TransportError

try:
    domain = client.domains.get(domain_id)
except ConflictError as error:
    print(error.code, error.request_id)
except SubdomainToError as error:
    print(error.status_code, error.code, error.request_id)
except TransportError as error:
    print(f"Network failure: {error}")

Specialized API exceptions cover 400, 401, 403, 404, 409, and 5xx. response_body preserves the original response.

Verify a webhook

PYTHON
from subdomainto import verify_webhook

event = verify_webhook(
    raw_body,
    signature_header,
    webhook_secret,
    tolerance=300,
)

Pass raw_body as bytes. Invalid signatures, timestamps, and payloads raise InvalidWebhookError.