Publish Instagram Stories
Use this guide when your app needs to publish a single Instagram Story through the UniPost API without accidentally sending it as a normal feed post.
platform_posts[] and put mediaType: "story" directly inside that destination's flat platform_options object.When to use this guide
Instagram Stories are a separate Instagram publishing surface. Use mediaType: "story" when the post should appear as ephemeral full-screen story content instead of a feed post or Reel.
Stories accept exactly one media item: one image or one video. If your user selects multiple assets, route the publish as a feed carousel instead, or ask the user to choose one asset for the Story.
Choose one request shape
UniPost supports both the recommended platform_posts[] request shape and the older account_ids shape. Do not combine their platform_options formats in one request.
| Shape | Where mediaType goes | Notes |
|---|---|---|
| New platform_posts[] | platform_posts[].platform_options.mediaType | Recommended for new integrations. The platform post is already scoped to one destination, so options are flat. |
| Legacy account_ids | platform_options.instagram.mediaType | Only use this with top-level account_ids. Keep it strict if an older integration still depends on this shape. |
| Mixed | platform_posts[].platform_options.instagram.mediaType | Invalid. UniPost returns 422 because the request mixes legacy platform-scoped options into the new shape. |
Validate before publishing
Call POST/v1/posts/validate with the exact payload you plan to publish. A valid request shape always returns 200, even when data.valid is false because the account, media, or platform constraints need attention.
If the request shape is mixed or otherwise outside the API contract, UniPost returns 422 with a remediation hint and docs_url. Fix that before retrying validation or publish.
Example workflow
Story media rules
| Field | Required | Limits | Notes |
|---|---|---|---|
| media_urls or media_ids | ✓ | Exactly 1 asset | Use a public hosted URL or a UniPost media_id that has finished uploading. |
| media type | ✓ | JPEG image, MP4 video, or MOV video | Stories do not accept text-only posts. |
| caption | X | Not rendered as a story text overlay | If the user needs visible text, bake it into the image or video before publishing. |
| platform_options.mediaType | ✓ | story | Use this flat key in the recommended platform_posts[] shape. |
Common errors
| Code | What it means | How to fix it |
|---|---|---|
| VALIDATION_ERROR | The request shape is invalid, often because platform_posts[] contains legacy platform_options.instagram. | Move mediaType directly under platform_posts[].platform_options, or switch fully to the legacy account_ids shape. |
| instagram_story_single_media_only | The Story request contains zero media items or more than one media item. | Send exactly one image or one video for the Instagram destination. |
| invalid_instagram_media_type | The Instagram mediaType value is not one of the supported surfaces. | Use feed, reels, or story. |
| media_not_uploaded | A supplied media_id is still pending. | Upload bytes to the upload_url, then poll GET/v1/media/:media_id until the media is uploaded. |