Copy page

Guides

Creating Stories

Stories are ephemeral posts that disappear after 24 hours. OmniSocials supports stories on Instagram and Facebook. Snapchat stories are on the roadmap.

Stories use the same POST /posts/create endpoint as regular posts. The difference is type: "story" and the fact that media is required.

Supported channels

Channel ID	Platform	Supported
instagram	Instagram	✅
facebook	Facebook	✅
snapchat	Snapchat	coming soon

Calling POST /posts/create with type: "story" and a channel that does not support stories (LinkedIn, X, Pinterest, etc.) returns 400.

Minimal example

Code
curl -X POST https://api.omnisocials.com/v1/posts/create \
  -H "Authorization: Bearer $OMNISOCIALS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "story",
    "accounts": ["your-instagram-account-id"],
    "media_urls": ["https://example.com/story.jpg"]
  }'

Stories always require at least one media file. A story request with no media_ids and no media_urls returns 400.

Text on stories

Stories do not have captions the way feed posts do. The content field is optional on stories and, when provided, is used as internal notes in your OmniSocials dashboard. It is not rendered on the published story.

If you want text to appear on the story visual itself, bake it into the image or video before uploading. OmniSocials does not composite text onto media at publish time.

Cross-posting a story to Instagram and Facebook

Pass both account IDs. Both platforms get the same media.

Code
{
  "type": "story",
  "accounts": [
    "your-instagram-account-id",
    "your-facebook-page-account-id"
  ],
  "media_urls": ["https://example.com/story-9x16.jpg"]
}

If you need different visuals for each (e.g. to tune the crop or overlay), use the per-platform media_urls shape with channel IDs as keys:

Code
{
  "type": "story",
  "accounts": [
    "your-instagram-account-id",
    "your-facebook-page-account-id"
  ],
  "media_urls": {
    "instagram": ["https://example.com/ig-story.jpg"],
    "facebook": ["https://example.com/fb-story.jpg"]
  }
}

Media requirements

Platform	Image	Video
Instagram	JPEG or PNG, 9:16 recommended	MP4, up to 60 seconds, max 100 MB
Facebook	JPEG or PNG, 9:16 recommended	MP4, up to 60 seconds

Stories on both platforms prefer a 9:16 vertical aspect ratio (e.g. 1080 × 1920). Images outside 9:16 are still accepted but are center-cropped or letterboxed by the platform.

Carousels in stories

Stories are always single-media. Unlike feed posts, you cannot create a multi-image or multi-video story in a single request. If you want to publish several stories in a row, make multiple POST /posts/create calls. Each one becomes a separate story.

Scheduling stories

Stories are schedulable the same way as feed posts. Add scheduled_at (ISO 8601 UTC) and OmniSocials publishes the story at the scheduled time.

Code
{
  "type": "story",
  "accounts": ["your-instagram-account-id"],
  "media_urls": ["https://example.com/story.jpg"],
  "scheduled_at": "2026-04-18T14:00:00Z"
}

Because stories only live for 24 hours, scheduling them for a specific moment (e.g. "go live when my campaign starts") is usually more useful than the fire-and-forget pattern of feed posts.

What happens after 24 hours

OmniSocials does not delete the story record from your workspace after the 24 hour window closes. The post still appears in GET /posts with status: "posted". The urls field still points at the now-expired story on the platform. Clicking the URL after 24 hours typically returns a 404 or redirects to the account's profile.

If you want to archive a story (save it permanently to your profile's Highlights or similar), do that in the native app. OmniSocials does not currently expose a "highlight" action through the API.

Limitations

• Stories cannot contain multi-media carousels. One file per request.
• The content field is not rendered on the story itself. Any text you want visible must be baked into the media.
• Stories cannot be updated after publishing. To change a story, delete and recreate.
• type: "story" is rejected on platforms that do not support stories (all platforms except Instagram and Facebook today). Mixing story-capable and non-story-capable channels in the same accounts array returns 400.
• Snapchat Spotlight and Stories are on the roadmap, not shipped yet

Related reading

• Creating Posts for the full field reference
• Cross-Posting for the one-request-many-platforms model
• Platforms for per-platform media specs