Posts
Publish reels on Instagram via API
With format reels and one video in media, Connect publishes a reel on the Instagram account your customer connected. One call works for every account, with no app review and no token storage.
The request
POST /api/posts?customer_integration=<connection uuid>
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
Idempotency-Key: <unique key>
{
"external_reference": "reel-310",
"format": "reels",
"caption": "Bastidores da campanha #reels",
"media": [
{
"type": "video",
"url": "https://cdn.example.com/reel.mp4"
}
],
"instagram": {
"share_to_feed": true,
"cover_url": "https://cdn.example.com/capa.jpg",
"first_comment": "Qual parte você mais gostou?"
}
}What you can do
- Publish a reel from a public https:// video URL.
- Pick a cover image with instagram.cover_url.
- Decide whether the reel also shows on the profile grid with instagram.share_to_feed.
- Use an Instagram audio with audio_id and adjust audio_volume and video_volume.
- Add collaborators, a location, a first comment and turn comments off.
Rules and limits
- Reels takes exactly 1 video.
- The caption goes up to 2200 characters, with at most 30 hashtags and 20 mentions.
- share_to_feed defaults to true.
- audio_volume and video_volume require audio_id.
- The answer is 202: publishing runs in the background and you follow it with GET /posts/{uuid}.
- external_reference is required (409 if an equal publication exists) and Idempotency-Key, up to 255 characters, returns the stored post with 200 on replay.
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. |
| caption | string | No | Caption. On Instagram, up to 2200 characters, 30 hashtags and 20 mentions. Stories carry no caption. |
| media | array | Yes | List of media, in order. Each item has type and url. |
| media.url | string | Yes | Public https:// URL the network can download (up to 2048 characters). |
| instagram.share_to_feed | boolean | No | Whether the reel also shows on the profile grid. Reels only. |
| instagram.cover_url | string | No | https:// URL of the reel's cover image. Reels only. |
| instagram.audio_id | string | No | Id of an Instagram audio for the reel. Reels only. |
Who it is for
Short-video tool
Your editor exports the video and publishes the reel straight to the user's account, with cover and caption set on the spot.
Agency with many clients
One flow publishes the same reel to dozens of connected Instagram accounts, each with its own customer_integration.
Social media AI agent
An agent generates the video, picks the cover and publishes the reel, with the first comment ready to go.
Works with
Instagram Business
Instagram
Frequently asked questions
Can I publish a single video as feed?
No. A single video must go as reels; feed is for 1 image or a carousel of 2 to 10 media items.
Does the reel show on the profile grid?
By default yes, because share_to_feed is true. Send instagram.share_to_feed as false to keep it off.
Does it work with instagram and instagram_business accounts?
Yes. Both connections take the same POST /posts and the same instagram block.
See Connect applied to your product.
Try it for 15 days with no card, or walk our team through your use case.
