Instagram Publishing API Documentation

Kavenio publishes Instagram content through connected Instagram Business or Creator accounts. Use instagram as the platform value and put Instagram-specific fields in platformSpecificData. Instagram publishing uses Meta media containers. Kavenio creates the container, waits for provider processing, publishes it, and then creates optional first comments for supported content types. First comments require the instagram_business_manage_comments permission.

Quick Reference

Capability	Support
Platform key	`instagram`
Feed post	One image, one video, or 2-10 image/video carousel
Reel	One video with `contentType: "reels"`
Story	One image or one video, no caption
First comment	Feed, carousel, and Reels; requires comment-management permission
Collaborators	Feed, carousel, and Reels
User tags	Image feed posts and image carousel items
Post analytics	`GET /v1/analytics` for views, reach, likes, comments, saves, shares
Native edit/unpublish	Not supported

Create A Feed Post

{
  "content": "Launch photo caption.",
  "mediaItems": [
    {
      "type": "image",
      "url": "https://cdn.example.com/instagram-launch.jpg",
      "mimeType": "image/jpeg"
    }
  ],
  "platforms": [
    {
      "platform": "instagram",
      "accountId": "acc_123",
      "platformSpecificData": {
        "contentType": "feed",
        "firstComment": "Full launch notes: https://example.com/launch",
        "collaborators": ["partner_brand"],
        "userTags": [
          {
            "username": "partner_brand",
            "x": 0.5,
            "y": 0.5
          }
        ]
      }
    }
  ],
  "publishNow": true
}

kavenio posts create \
  --content "Launch photo caption." \
  --publish-now \
  --media-url https://cdn.example.com/instagram-launch.jpg \
  --platform instagram:acc_123 \
  --content-type feed \
  --first-comment "Full launch notes: https://example.com/launch"

contentType defaults to feed, so you can omit it for normal feed posts. First comments require instagram_business_manage_comments for direct Instagram Login connections. Older Facebook-linked connections require instagram_manage_comments and pages_read_engagement. Kavenio checks the stored scopes before creating the main media container.

Create A Reel

Use contentType: "reels" for Instagram Reels.

{
  "content": "Reel caption.",
  "mediaItems": [
    {
      "type": "video",
      "url": "https://cdn.example.com/reel.mp4",
      "mimeType": "video/mp4",
      "thumbnail": "https://cdn.example.com/reel-cover.jpg"
    }
  ],
  "platforms": [
    {
      "platform": "instagram",
      "accountId": "acc_123",
      "platformSpecificData": {
        "contentType": "reels",
        "shareToFeed": true,
        "thumbOffset": 1000,
        "firstComment": "Pinned Reel follow-up",
        "collaborators": ["partner_brand"],
        "trialParams": {
          "graduationStrategy": "MANUAL"
        },
        "audioName": "Original audio"
      }
    }
  ],
  "publishNow": true
}

instagramThumbnail overrides the media item’s thumbnail when both are present.

Create A Story

Use contentType: "story" for Stories.

{
  "content": "",
  "mediaItems": [
    {
      "type": "image",
      "url": "https://cdn.example.com/story.jpg",
      "mimeType": "image/jpeg"
    }
  ],
  "platforms": [
    {
      "platform": "instagram",
      "accountId": "acc_123",
      "platformSpecificData": {
        "contentType": "story"
      }
    }
  ],
  "publishNow": true
}

Stories require exactly one image or video. Instagram Story publishing does not support captions, first comments, collaborators, user tags, Reel options, or advanced Story options in v1. Stories require an Instagram Business account.

First Comments And Permissions

Kavenio creates platformSpecificData.firstComment after the feed post, carousel, or Reel publishes. Instagram connections request instagram_business_manage_comments in addition to the basic and content publishing permissions. Accounts connected before the comment-management permission was added must reconnect before publishing a first comment. Kavenio rejects a first-comment request before uploading media when a stored credential is known to lack that permission. If Instagram accepts the media publish and then rejects the comment, the target failure details preserve the published media ID and provider response so the partial result can be reconciled without publishing the media twice.

Platform-Specific Fields

Field	Type	Behavior
`contentType`	`"feed"` \| `"story"` \| `"reels"`	Selects the Instagram publish path. Defaults to feed.
`firstComment`	string	Created after feed, carousel, or Reel publish. Requires `instagram_business_manage_comments`; unsupported for Stories.
`collaborators`	string[]	Up to 3 collaborator usernames for feed, carousel, and Reels.
`userTags`	array	Image feed and image carousel tags with `username`, `x`, `y`, and optional `mediaIndex`.
`shareToFeed`	boolean	Reel option.
`thumbOffset`	integer	Reel thumbnail offset.
`instagramThumbnail`	URL string	Reel cover URL. Overrides media item thumbnail.
`trialParams.graduationStrategy`	`"MANUAL"` \| `"SS_PERFORMANCE"`	Reel trial parameter.
`audioName`	string	Reel audio label.

Media Limits

Kavenio validates supplied media metadata before calling Meta:

Media	Limit
Feed images	JPEG, 8 MB, aspect ratio 4:5 to 1.91:1
Feed videos	MP4/MOV, 3 seconds to 60 minutes, 300 MB, 4:5 to 1.91:1
Feed carousel	2-10 image/video items
Reels	One MP4/MOV video, 3 seconds to 15 minutes, 300 MB, 23-60 FPS, aspect ratio 0.01:1 to 10:1; 9:16 recommended
Stories	One JPEG image or MP4/MOV video
Story videos	3 to 60 seconds, 100 MB, 23-60 FPS, aspect ratio 0.1:1 to 10:1; 9:16 recommended

Meta can still reject media after fetching the URL if the actual file does not match the metadata or current Instagram API constraints. Media URLs must be public and fetchable by Meta. Before creating a container, Kavenio checks Instagram’s content_publishing_limit. Instagram allows 100 API-published posts per professional account in a rolling 24-hour window. A full quota is returned as a retryable rate-limit failure without creating a container.

Scheduling

Use Kavenio’s normal scheduledFor field. Kavenio creates the Meta media container when the scheduled job runs, so media URLs must remain valid until publish time.

Unsupported Cases

Kavenio does not support these Instagram actions through post publishing:

text-only Instagram posts
Story captions
Story first comments
Story stickers, links, mentions, or other advanced Story options
user tags on videos
native edit or unpublish after publication

Common Errors

Error	Meaning	Fix
`Instagram feed publishing requires one image or a 2-10 item carousel.`	Feed media count is invalid.	Send one image/video or a 2-10 item carousel.
`Instagram Story publishing does not support captions.`	Story `content` is not empty.	Omit Story caption text.
`Instagram advanced Story options are not implemented in this slice.`	A Story target included unsupported options.	Remove first comments, collaborators, tags, and Reel-only fields.
`Instagram Reel publishing requires exactly one video media item.`	Reel media is missing or not a single video.	Send one video media item.
`Instagram video media must use MP4 or MOV.`	Video MIME metadata is unsupported.	Host an MP4 or MOV file.
`Connected Instagram credential does not include ... required for first comments.`	The saved connection lacks comment-management permission for its login mode.	Reconnect Instagram or omit `firstComment`.

​Quick Reference

​Create A Feed Post

​Create A Reel

​Create A Story

​First Comments And Permissions

​Platform-Specific Fields

​Media Limits

​Scheduling

​Unsupported Cases

​Common Errors