Posts
Publish stories on Instagram via API
With format story, Connect publishes the media as a story on the Instagram account your customer connected. It is the same POST /posts call as the other formats, for any connected account.
The request
POST /api/posts?customer_integration=<connection uuid>
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
Idempotency-Key: <unique key>
{
"external_reference": "story-77",
"format": "story",
"media": [
{
"type": "image",
"url": "https://cdn.example.com/story.jpg"
}
],
"instagram": {
"collaborators": [
"marca_parceira"
]
}
}What you can do
- Publish a story from a public https:// image or video URL.
- Invite collaborators with instagram.collaborators.
- Tag users on the media with media[].user_tags.
- Target the account by customer_integration or by integration_slug and source_name.
Rules and limits
- Stories carry no caption: do not send caption.
- In the instagram block, a story accepts only collaborators, up to 5, without @.
- Up to 10 media per call, each one becomes a story, published in order. The network checks every file before the first one goes out, so a broken file never leaves the sequence half published.
- The answer is 202: publishing runs in the background. Follow it with GET /posts/{uuid}.
- external_reference is required and Idempotency-Key avoids duplicating the call.
Main fields
| Field | Type | Required | Description |
|---|---|---|---|
| external_reference | string | Yes | The post's id in your system (up to 100 characters). Prevents publishing the same post twice on the same account. |
| format | string | Yes | Post format. On Instagram: feed, reels or story. On Facebook: feed, reels or story. |
| media | array | Yes | List of media, in order. Each item has type and url. |
| media.type | string | Yes | Media type: image, video or document (document is LinkedIn only). |
| media.url | string | Yes | Public https:// URL the network can download (up to 2048 characters). |
| instagram.collaborators | array | No | Up to 5 users invited as collaborators, without @. Works on feed, reels and story. |
Who it is for
Alerts and promotions
Your SaaS publishes a flash-sale story on the customer's account the moment the user hits publish.
Events tool
Generate a story with the event artwork for each attendee and publish it on each one's account.
AI agent
An agent turns a brand news item into a vertical image and publishes it as a story automatically.
Works with
Instagram Business
Instagram
Frequently asked questions
Can I add a caption to a story?
No. Stories carry no caption; the text has to be in the image or video itself.
Which instagram block options work on a story?
Only collaborators. The other options are for feed and reels.
Does it work on instagram and instagram_business accounts?
Yes, both connections accept format story.
See Connect applied to your product.
Try it for 15 days with no card, or walk our team through your use case.
