postdom

Typed synchronous and asynchronous Python clients for the Postdom short-form publishing API.

pip install postdom

from pathlib import Path
import os

from postdom import Postdom

with Postdom(os.environ["POSTDOM_API_KEY"]) as postdom:
    upload = postdom.upload_media(
        Path("launch.mp4").read_bytes(),
        content_type="video/mp4",
        platforms=["tiktok"],
    )
    media = postdom.wait_for_media(upload.media_handle)
    if media.status != "stored":
        raise RuntimeError(f"Media is {media.status}")

    submission = postdom.publish_video(
        account_ids=["account-tiktok"],
        media_handle=media.media_handle,
        caption="Launch day. Here is what we shipped.",
        intent="Announce the launch",
    )
    result = postdom.wait_for_publish(submission.id)
    print(result.status)

The async client has the same Python operation names:

import os

from postdom import AsyncPostdom


async def workspace_status():
    async with AsyncPostdom(os.environ["POSTDOM_API_KEY"]) as postdom:
        return await postdom.get_workspace_status()

Contract

The package mirrors the 14 agent-authority operations in @postdom/sdk:

• get_workspace_status, list_accounts, connect_account
• create_media_upload, get_media_status, upload_media, wait_for_media
• submit_plan, get_plan
• publish_video, get_post, wait_for_publish
• get_post_performance, get_account_performance, get_best_posts
• get_brief, get_digest

Responses are Pydantic v2 models. Models allow additive server fields so a harmless API addition does not break existing applications. The checked-in contract suite locks operation paths, platforms, statuses, metrics, limits, and media handles to the audited Node SDK, which is itself drift-tested against the live API route table and @postdom/core.

Authentication and safety

Use a workspace pd_live_ API key or pd_oauth_ OAuth access token. Both carry agent authority: approval, billing, and dashboard administration remain human-only and return 403 agent_token_forbidden by design. Credentials are held as Pydantic SecretStr values and never appear in client representations or SDK-generated errors.

publish_video defaults TikTok to SELF_ONLY, Instagram to a Reel with AI disclosure, and YouTube to private with synthetic-media disclosure. It generates one idempotency key and reuses it across safe retries. connect_account is never retried because it has no idempotency key.

upload_media sends bytes through a separate HTTP client directly to the short-lived signed storage URL. The Postdom bearer credential is never attached to that PUT, the PUT is never retried, and the signed URL is not returned from the high-level result.

Errors

Non-2xx responses raise typed subclasses of PostdomAPIError, including PostdomAuthenticationError, PostdomScopeError, PostdomHumanRouteError, PostdomBillingError, PostdomRateLimitError, and PostdomServerError. Network and deadline failures use PostdomConnectionError and PostdomTimeoutError.

Release status

Version 0.1.0 is the initial package version. PyPI publishing is held until Dean explicitly authorizes it; building and audit do not imply registry publication.