Instagram

Publish images with captions to an Instagram Business or Creator account.

Connect

OAuth (browser). Ask Herald for a hosted connect URL and send the user there:

curl -X POST https://api.herald.leiritech.com/v1/accounts/connect \
  -H "Authorization: Bearer hld_…" -H "Content-Type: application/json" \
  -d '{"network":"instagram","redirect_url":"https://your-app.example/connected"}'

{ "connect_url": "https://herald.leiritech.com/api/oauth/connect/…", "expires_at": "…" }

The user authorizes at Instagram; the account then appears in GET /v1/accounts.

Prerequisites (owner): a Meta app with Instagram Login, its App ID/Secret saved in admin → Platform apps, and App Review for instagram_business_content_publish for public use (your own account works in dev/tester mode).

Publish

Instagram requires a hosted image URL, so upload the image first, then publish:

# 1) upload the image → media id
curl -X POST https://api.herald.leiritech.com/v1/media \
  -H "Authorization: Bearer hld_…" -F "file=@photo.jpg"
# → { "id": "b1c2…", "public_url": "https://cdn…/img.jpg", "bytes": 84213, "kind": "image" }

# 2) publish
curl -X POST https://api.herald.leiritech.com/v1/posts \
  -H "Authorization: Bearer hld_…" -H "Content-Type: application/json" \
  -d '{"targets":["<ig-account-uuid>"],"text":"Launch day! ✨","media_ids":["b1c2…"],"mode":"now"}'

{
  "id": "1a00…", "status": "published", "text": "Launch day! ✨",
  "targets": [{ "network": "instagram", "status": "published",
    "permalink": "https://www.instagram.com/p/Cxyz…/", "platform_post_id": "1789…" }]
}

Rules & gotchas

• Exactly one image is required — Instagram has no text-only posts via the API.
• Image should be JPEG/PNG, ≥320px wide, aspect ratio between 4:5 and 1.91:1, under 8 MB.
• Only Business/Creator accounts linked correctly can publish; a Personal account is rejected at connect time (personal_account).
• No API delete — unpublish returns unsupported for Instagram; remove posts in the app.
• Stats collected: followers / following / media count; likes / comments per post (reach/views need the insights permission).