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

FieldTypeRequiredDescription
external_referencestringYesThe post's id in your system (up to 100 characters). Prevents publishing the same post twice on the same account.
formatstringYesPost format. On Instagram: feed, reels or story. On Facebook: feed, reels or story.
captionstringNoCaption. On Instagram, up to 2200 characters, 30 hashtags and 20 mentions. Stories carry no caption.
mediaarrayYesList of media, in order. Each item has type and url.
media.urlstringYesPublic https:// URL the network can download (up to 2048 characters).
instagram.share_to_feedbooleanNoWhether the reel also shows on the profile grid. Reels only.
instagram.cover_urlstringNohttps:// URL of the reel's cover image. Reels only.
instagram.audio_idstringNoId 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.

Related

See everything you can do with Posts

See Connect applied to your product.

Try it for 15 days with no card, or walk our team through your use case.