How to Automate Cross-Posting with Python

Step-by-step

1. 1

   Install the official Python SDK

   The codivupload package is published on PyPI. It's auto-generated from the OpenAPI spec, so every endpoint you see in api.codivupload.com is available as a typed method. The SDK has zero runtime dependencies beyond httpx and pydantic.

   pip install codivupload

2. 2

   Initialize the client

   Pass your API key to the constructor. The SDK reads CODIVUPLOAD_API_KEY from the environment if no key is passed explicitly — preferred for production deployments where the key lives in your secret manager. The client is thread-safe and reusable; instantiate it once at process startup.

   from codivupload import CodivUpload
   
   # Explicit:
   client = CodivUpload(api_key="YOUR_API_KEY")
   
   # Or via env var (recommended for production):
   # export CODIVUPLOAD_API_KEY=...
   client = CodivUpload()

3. 3

   Cross-post to multiple platforms in a single call

   Pass profile_name and a platforms array. CodivUpload publishes to each platform in parallel and returns a post_id you can poll. Per-platform overrides let you customize the post for each network without making separate calls — for example a longer description on LinkedIn, a different cover image on Instagram, and reply controls on X.

   post = client.posts.create(
       post_type="image",
       profile_name="my_brand",
       platforms=["instagram", "tiktok", "x", "linkedin", "facebook"],
       media_urls=["https://your-cdn.example.com/cover.jpg"],
       title="Product Launch — May 2026",
       description="Our biggest update yet. Read the full breakdown on the blog.",
       instagram_share_to_feed=True,
       instagram_alt_text="Product shot on a beige backdrop",
       x_reply_settings="following",
       linkedin_visibility="PUBLIC",
   )
   print(post.post_id, "→", post.destinations_count, "destinations")

4. 4

   Schedule for later instead of posting now

   Add scheduled_date as an ISO 8601 UTC string. CodivUpload queues the post inside pgmq and the worker fires at the exact timestamp. You can also use schedule_best_time=True (mutually exclusive with scheduled_date) to let CodivUpload pick the optimal slot based on the connected accounts' last 90 days of analytics.

   from datetime import datetime, timedelta, timezone
   
   # Post tomorrow at 14:00 UTC
   when = (datetime.now(timezone.utc) + timedelta(days=1)).replace(hour=14, minute=0, second=0)
   post = client.posts.create(
       post_type="video",
       profile_name="my_brand",
       platforms=["youtube", "tiktok", "instagram"],
       media_urls=["https://your-cdn.example.com/clip.mp4"],
       title="Tomorrow's tip",
       description="Save this for later — it's how I batch a week of content in 90 minutes.",
       scheduled_date=when.isoformat(timespec="seconds"),
       youtube_type="shorts",
   )

5. 5

   Poll for completion (or use webhooks)

   Posts go through scheduled → publishing → completed. Use the get method to poll, or — preferred for production — subscribe to the post.completed webhook event via /v1/webhooks. Webhooks fire on completed, partially_failed, and failed states with the full destinations payload included.

   import time
   
   while True:
       p = client.posts.get(post.post_id)
       if p.post.status in ("completed", "partially_failed", "failed"):
           break
       time.sleep(5)
   
   for d in p.destinations:
       if d.status == "success":
           print(f"✓ {d.platform}: {d.post_url}")
       else:
           print(f"✗ {d.platform}: {d.error_message}")

6. 6

   Handle partial failures

   When some platforms succeed and others fail, the parent post status becomes partially_failed. Inspect destinations[i].error_message to triage — common causes are platform-specific (TikTok rate limit, Instagram media format mismatch, YouTube quota exhausted). After fixing the underlying issue, retry only the failed destinations with client.posts.retry_failed(post_id), which re-queues them without reposting the already-successful ones.

Frequently asked