Skip to main content
Instagram supports image, carousel, and video posts. Text-only posts are not available through the unified API (Instagram requires media).

Connect

Requires an Instagram Business or Creator account linked to a Facebook Page.
curl -X POST "https://backend.postsiva.com/unified/oauth/url" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: psk_live_YOUR_KEY" \
  -d '{"platform": ["instagram"]}'
One Instagram account per workspace.

Post types

TypeEndpointMedia
ImagePOST /unified/post/imagedefault_image_id or default_image_url
CarouselPOST /unified/post/carouselimage_ids (2–20)
VideoPOST /unified/post/videovideo_id or video_url

Example: image post

curl -X POST "https://backend.postsiva.com/unified/post/image" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: psk_live_YOUR_KEY" \
  -d '{
    "platforms": ["instagram"],
    "default_text": "Summer collection is live. Link in bio.",
    "default_image_id": "your-media-uuid"
  }'

Caption limit

Instagram captions are capped at ~2,200 characters. Postsiva validates at 2,200 and returns 422 if exceeded:
{
  "detail": "Max text character limit for instagram is 2200. Received 2300 characters in instagram_text/default_text."
}
Override caption per platform:
{
  "platforms": ["instagram", "threads"],
  "default_text": "Shared caption.",
  "instagram": {
    "instagram_text": "Instagram-specific caption with #hashtags."
  }
}

Media requirements

Instagram has strict aspect ratio rules. Postsiva auto-fits images to allowed ratios (letterboxing) on upload when needed.
FormatGuidance
ImageJPEG/PNG; 4:5 to 1.91:1 aspect ratio recommended
Carousel2–20 images, same aspect ratio per slide
VideoMP4/MOV; Reels-compatible dimensions
See Media guidelines for full specs and upload flow.

Scheduling

{
  "platforms": ["instagram"],
  "default_text": "Launch day post.",
  "default_image_id": "media-uuid",
  "scheduled_time": "2026-07-20T12:00:00Z"
}
Or use POST /unified/scheduled-posts for schedule-only requests.

Multi-platform posting

Instagram pairs well with Facebook and Threads in one call:
{
  "platforms": ["instagram", "facebook", "threads"],
  "default_text": "Cross-posted launch announcement.",
  "default_image_id": "media-uuid",
  "facebook": {
    "facebook_page_ids": ["756356074224043"]
  }
}

Common errors

ErrorCauseFix
NOT_CONNECTEDInstagram not linkedConnect Business account via OAuth
422 caption limitOver 2,200 charactersShorten caption
Missing mediaNo image/video IDUpload via /media/* first