API Examples

Hello World

The simplest possible post — plain text to X only. No media, no scheduling, publishes immediately.

curl -X POST https://api.codivupload.com/v1/posts \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "post_type": "text",
    "profile_name": "my_brand",
    "platforms": ["x"],
    "description": "Hello from the CodivUpload API."
  }'

Expected response:

{
  "message": "Post successfully queued for immediate delivery.",
  "post_id": "550e8400-e29b-41d4-a716-446655440000",
  "destinations_count": 1,
  "received_type": "text",
  "is_immediate": true
}

Simple Text Post

curl -X POST https://api.codivupload.com/v1/posts \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "post_type": "text",
    "profile_name": "my_brand",
    "platforms": ["x", "threads", "bluesky"],
    "description": "Exciting news! Our new feature is live."
  }'

Instagram Carousel

curl -X POST https://api.codivupload.com/v1/posts \
  -H "Authorization: Bearer YOUR_KEY" \
  -d '{
    "post_type": "image",
    "profile_name": "my_brand",
    "platforms": ["instagram", "threads"],
    "media_urls": [
      "https://cdn.codivupload.com/.../photo1.jpg",
      "https://cdn.codivupload.com/.../photo2.jpg",
      "https://cdn.codivupload.com/.../photo3.jpg"
    ],
    "description": "Behind the scenes",
    "instagram_alt_text": "Team working on new designs"
  }'

YouTube Video with Captions

curl -X POST https://api.codivupload.com/v1/posts \
  -H "Authorization: Bearer YOUR_KEY" \
  -d '{
    "post_type": "video",
    "profile_name": "my_brand",
    "platforms": ["youtube"],
    "media_urls": ["https://cdn.codivupload.com/.../video.mp4"],
    "title": "Product Launch 2026",
    "description": "Full walkthrough of our new features.",
    "youtube_category_id": "28",
    "youtube_tags": ["product", "launch"],
    "youtube_thumbnail_url": "https://cdn.codivupload.com/.../thumb.jpg",
    "youtube_caption_url": "https://cdn.codivupload.com/.../captions.srt",
    "youtube_caption_language": "en",
    "first_comment": "What do you think?"
  }'

Multi-Platform with Different Media

Send different video files per platform — useful when you have both horizontal and vertical cuts:

curl -X POST https://api.codivupload.com/v1/posts \
  -H "Authorization: Bearer YOUR_KEY" \
  -d '{
    "post_type": "video",
    "profile_name": "my_brand",
    "platforms": ["youtube", "tiktok", "instagram"],
    "media_urls": ["https://cdn.codivupload.com/.../horizontal.mp4"],
    "tiktok_media_urls": ["https://cdn.codivupload.com/.../vertical.mp4"],
    "instagram_media_urls": ["https://cdn.codivupload.com/.../square.mp4"],
    "title": "Day in my life",
    "instagram_media_type": "REELS"
  }'

YouTube Shorts

curl -X POST https://api.codivupload.com/v1/posts \
  -H "Authorization: Bearer YOUR_KEY" \
  -d '{
    "post_type": "video",
    "profile_name": "my_brand",
    "platforms": ["youtube"],
    "media_urls": ["https://cdn.codivupload.com/.../short.mp4"],
    "title": "Quick tip #shorts",
    "youtube_type": "shorts"
  }'

Add to Queue

curl -X POST https://api.codivupload.com/v1/posts \
  -H "Authorization: Bearer YOUR_KEY" \
  -d '{
    "post_type": "image",
    "profile_name": "my_brand",
    "platforms": ["instagram", "facebook"],
    "media_urls": ["https://cdn.codivupload.com/.../design.png"],
    "description": "Fresh designs",
    "add_to_queue": true
  }'

TikTok Draft Mode

curl -X POST https://api.codivupload.com/v1/posts \
  -H "Authorization: Bearer YOUR_KEY" \
  -d '{
    "post_type": "video",
    "profile_name": "my_brand",
    "platforms": ["tiktok"],
    "media_urls": ["https://cdn.codivupload.com/.../clip.mp4"],
    "tiktok_post_mode": "MEDIA_UPLOAD"
  }'

In MEDIA_UPLOAD mode, the video is sent to TikTok inbox/drafts. Add details in the TikTok app before publishing.

Update a Post

Update caption, scheduled time, or other fields on a post that hasn't been published yet.

curl -X POST https://api.codivupload.com/v1/posts/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated caption with new hashtags #product #launch",
    "scheduled_date": "2026-04-20T14:00:00Z"
  }'

Delete a Post

Cancel a scheduled post before it publishes. Published posts cannot be deleted via this endpoint.

curl -X DELETE https://api.codivupload.com/v1/posts/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_KEY"

# 204 No Content on success

Error Response Examples

400 — Validation error (e.g., text too long, unsupported post type for platform)

{
  "error": "Validation failed",
  "details": [
    {
      "field": "description",
      "message": "Exceeds X character limit of 280. Current length: 347.",
      "platform": "x"
    }
  ]
}

429 — Rate limit reached (platform daily post limit exceeded)

{
  "error": "Daily post limit reached for platform: instagram",
  "code": "PLATFORM_RATE_LIMIT",
  "retry_after": 39600,
  "platform": "instagram",
  "limit": 25,
  "resets_at": "2026-04-16T00:00:00Z"
}