Posts

Publish to Instagram through the shared POST /v1/posts surface.

Cross-platform flow: Media guide.

Supported formats

`mediaKind`	Supported	With caption	Notes
`image`	Yes	Yes	Single image URL
`multi-image`	Yes	Yes	2–10 image/video URLs
`video`	Yes	Yes	Single video URL; published as a Reel (also appears in feed)
`stories`	Yes	No	Image or video story

Instagram does not support text-only posts. At least one media URL and an explicit mediaKind (image, multi-image, video, or stories) are required.

Features

Feature	Supported	Notes
Thread	No	X-only
Quote	No	X-only
Schedule	Yes	`scheduledFor` + `timezone`
Remote delete	No	Not available with Instagram Login (`MEDIA_DELETE_UNSUPPORTED`)

Create

curl -X POST https://api.onepostly.com/v1/posts \
  -H "x-api-key: op_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello from Onepostly",
    "mediaKind": "image",
    "mediaUrls": ["https://cdn.example.com/photo.jpg"],
    "destinations": [
      { "connectionId": "YOUR_INSTAGRAM_CONNECTION_ID" }
    ]
  }'

{
  "text": "Hello from Onepostly",
  "mediaKind": "image", // image | multi-image | video | stories
  "mediaUrls": ["https://cdn.example.com/photo.jpg"],
  "destinations": [
    { "connectionId": "YOUR_INSTAGRAM_CONNECTION_ID" }
  ]
}

Response: 202 with status: "queued". Poll GET /v1/posts/:id until the destination is published or failed — or use webhooks instead of polling.

Image

{
  "text": "Caption optional",
  "mediaKind": "image",
  "mediaUrls": ["https://cdn.example.com/photo.jpg"],
  "destinations": [{ "connectionId": "YOUR_INSTAGRAM_CONNECTION_ID" }]
}

Multi-image

{
  "text": "Multi-image caption",
  "mediaKind": "multi-image",
  "mediaUrls": [
    "https://cdn.example.com/1.jpg",
    "https://cdn.example.com/2.jpg",
    "https://cdn.example.com/clip.mp4"
  ],
  "destinations": [{ "connectionId": "YOUR_INSTAGRAM_CONNECTION_ID" }]
}

Requires 2–10 URLs (INVALID_MULTI_IMAGE otherwise)
Mix of images and videos allowed

Video

{
  "text": "Reel caption",
  "mediaKind": "video",
  "mediaUrls": ["https://cdn.example.com/video.mp4"],
  "destinations": [{ "connectionId": "YOUR_INSTAGRAM_CONNECTION_ID" }]
}

Video publishes as a Reel (also shared to feed).

Stories

{
  "mediaKind": "stories",
  "mediaUrls": ["https://cdn.example.com/story.jpg"],
  "destinations": [{ "connectionId": "YOUR_INSTAGRAM_CONNECTION_ID" }]
}

Image or video URL supported
Caption is not applied on Stories

Pass scheduledFor (timezone-naive local datetime, e.g. 2026-07-16T12:00:00) and timezone (IANA, e.g. America/New_York). Defaults to UTC when timezone is omitted. Do not send Z or a numeric offset on scheduledFor. Future times stay scheduled until publish time.

Media

POST /v1/media (multipart file) → CDN url
Pass that URL in mediaUrls on create post
Instagram requires a public HTTPS URL it can download

Details and limits: Media.

Publish errors (Instagram)

Code	When
`MEDIA_REQUIRED`	No media URL for image / video / stories
`INVALID_MULTI_IMAGE`	Fewer than 2 or more than 10 multi-image URLs
`INVALID_MEDIA`	Unsupported or invalid media
`MEDIA_UNFETCHABLE`	Instagram could not download the URL (must be public HTTPS)
`CONTAINER_FAILED`	Media processing failed or expired
`TOKEN_INVALID`	Reconnect account
`PERMISSION_DENIED`	Missing `instagram_business_content_publish` → reconnect
Rate limit	Transient — retry later