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

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.
mediaarrayYesList of media, in order. Each item has type and url.
media.typestringYesMedia type: image, video or document (document is LinkedIn only).
media.urlstringYesPublic https:// URL the network can download (up to 2048 characters).
instagram.collaboratorsarrayNoUp 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.

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.