Requirements

Use a professional Instagram account with a healthy connection and publishing permission. GET /accounts exposes accountType (business, creator, or unknown) and current capabilities. Each request targets exactly one account and confirmed media in its workspace.

Supported formats

Use an instagram object; omit posts, video, youtube, and facebook. FEED accepts a single JPEG or a 2–10 item JPEG/video carousel. REELS requires one video. STORIES requires one JPEG or video and rejects caption.

For formats that need media, complete the upload guide: reserve → PUT → confirm. Only confirmed mediaId values can be published. Slides made with Create a carousel already have a mediaId you can use without uploading.

Publish a post

Account and media UUIDs are illustrative; replace them with real IDs. Set your API key in the POSTEADY_API_KEY environment variable.

curl --request POST "https://www.posteady.com/api/v1/posts" \
  --header "Authorization: Bearer $POSTEADY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "accountIds": [
    "11111111-1111-4111-8111-111111111111"
  ],
  "instagram": {
    "requestId": "33333333-3333-4333-8333-333333333333",
    "contentType": "FEED",
    "caption": "Our latest release",
    "items": [
      {
        "mediaId": "22222222-2222-4222-8222-222222222222",
        "altText": "Our new product on a desk"
      }
    ]
  }
}'

Each JSON block below is a complete, separate request body. Supply real media IDs of the stated type and use a new requestId for each different operation. Keep the previous ID only when retrying that same operation.

Carousel

{
  "accountIds": [
    "11111111-1111-4111-8111-111111111111"
  ],
  "instagram": {
    "requestId": "33333333-3333-4333-8333-333333333333",
    "contentType": "FEED",
    "items": [
      {
        "mediaId": "22222222-2222-4222-8222-222222222222"
      },
      {
        "mediaId": "66666666-6666-4666-8666-666666666666"
      }
    ]
  }
}

Reel

{
  "accountIds": [
    "11111111-1111-4111-8111-111111111111"
  ],
  "instagram": {
    "requestId": "33333333-3333-4333-8333-333333333333",
    "contentType": "REELS",
    "items": [
      {
        "mediaId": "22222222-2222-4222-8222-222222222222"
      }
    ],
    "shareToFeed": true
  }
}

Story

{
  "accountIds": [
    "11111111-1111-4111-8111-111111111111"
  ],
  "instagram": {
    "requestId": "33333333-3333-4333-8333-333333333333",
    "contentType": "STORIES",
    "items": [
      {
        "mediaId": "22222222-2222-4222-8222-222222222222"
      }
    ]
  }
}

Confirm success

HTTP 202 means the job was accepted. Store results[0].jobId, then read its status below and wait for status: published. Replace the illustrative ID with the returned value.

curl --request GET "https://www.posteady.com/api/v1/publish-jobs/44444444-4444-4444-8444-444444444444" \
  --header "Authorization: Bearer $POSTEADY_API_KEY"

To schedule, send the same platform input to /scheduled-posts with a future scheduledAt and optional timezone. For asynchronous platforms, generate a UUID requestId per operation and retain it for retries.

Schedule and cancel · Read posts and metrics · Retries · MCP tools

Limits and errors

JPEG files allow up to 8 MiB. Instagram videos allow up to 1 GiB and 3 seconds–15 minutes; Story videos must be at most 60 seconds. A single FEED video is rejected: use REELS or include it in a carousel. Captions allow 2,200 Unicode characters. altText allows 1,000 and is only valid for FEED images. shareToFeed is REELS-only. Meta validates codec, frame rate, bitrate, and aspect ratio during processing. Platform publishing quotas can cause the asynchronous job to fail.

Publishing reference · Troubleshooting

More related guides

Instagram

On this page