Instagram

Overview

Publish feed posts, reels, and carousels to Instagram through PostPeer's unified API. PostPeer handles the Instagram Graph API complexity, including the async media publishing flow.

Note: Instagram requires a Business or Creator account linked to a Facebook Page. PostPeer's OAuth flow handles this connection.

Quick Start

1. Connect an Instagram Account

curl https://api.postpeer.dev/v1/connect/instagram \
  -H "x-access-key: YOUR_API_KEY"

Returns an OAuth URL for Facebook/Instagram authorization. The user must have an Instagram Business Account linked to a Facebook Page. See Connect Accounts for the full OAuth flow.

2. Get the Account ID

curl https://api.postpeer.dev/v1/connect/integrations \
  -H "x-access-key: YOUR_API_KEY"

Find the integration with "platform": "instagram" and note the id.

3. Publish a Post

curl -X POST "https://api.postpeer.dev/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "New product launch! #startup #launch",
    "platforms": [
      { "platform": "instagram", "accountId": "ig_456" }
    ],
    "mediaItems": [
      { "type": "image", "url": "https://cdn.example.com/photo.jpg" }
    ],
    "publishNow": true
  }'

Response:

{
	"success": true,
	"status": "published",
	"postId": "post_def456",
	"platforms": [
		{
			"platform": "instagram",
			"success": true,
			"platformPostUrl": "https://www.instagram.com/p/ABC123/"
		}
	]
}

Features

Feed Posts

Single image or video posts with captions and hashtags. Instagram requires at least one media item — text-only posts are not supported.

Reels

Upload short-form vertical videos as Instagram Reels:

curl -X POST "https://api.postpeer.dev/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Quick tutorial #reels",
    "platforms": [
      { "platform": "instagram", "accountId": "ig_456" }
    ],
    "mediaItems": [
      { "type": "video", "url": "https://cdn.example.com/reel.mp4" }
    ],
    "publishNow": true
  }'

By default Instagram auto-picks a frame from the video as the Reel cover. To override, pass a public image URL via platformSpecificData.coverUrl, or a timestamp via platformSpecificData.thumbOffset. coverUrl takes precedence when both are set.

curl -X POST "https://api.postpeer.dev/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Quick tutorial #reels",
    "platforms": [
      {
        "platform": "instagram",
        "accountId": "ig_456",
        "platformSpecificData": {
          "coverUrl": "https://cdn.example.com/reel-cover.jpg"
        }
      }
    ],
    "mediaItems": [
      { "type": "video", "url": "https://cdn.example.com/reel.mp4" }
    ],
    "publishNow": true
  }'

Requirements:

coverUrl must be a publicly accessible HTTPS URL. JPEG or PNG.
The image aspect ratio should match the video (9:16 for Reels) — Instagram rejects mismatches.
thumbOffset is an integer in milliseconds. Instagram extracts the video frame at that timestamp.
Both fields are ignored on non-video posts.

Reels default to also appearing in the account's main feed grid. To publish to Reels only, pass shareToFeed: false:

"platformSpecificData": { "shareToFeed": false }

Carousels

Create carousel posts with up to 10 images or videos by passing multiple mediaItems:

curl -X POST "https://api.postpeer.dev/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Swipe through our latest designs",
    "platforms": [
      { "platform": "instagram", "accountId": "ig_456" }
    ],
    "mediaItems": [
      { "type": "image", "url": "https://cdn.example.com/slide1.jpg" },
      { "type": "image", "url": "https://cdn.example.com/slide2.jpg" },
      { "type": "image", "url": "https://cdn.example.com/slide3.jpg" }
    ],
    "publishNow": true
  }'

Media Requirements

Type	Formats	Aspect Ratios	Duration
Image	JPG, PNG	1:1, 4:5, 1.91:1	—
Video (feed)	MP4	1:1, 4:5	3-60 seconds
Video (reel)	MP4	9:16	3-90 seconds
Carousel	JPG, PNG, MP4	1:1	Up to 10 items

PostPeer validates media against these requirements before publishing.