How to Schedule Instagram Posts via API

Step-by-step

1. 1

   Connect Instagram inside a CodivUpload profile

   Profiles in CodivUpload group all the social accounts that belong to a single brand or client. In Dashboard → Profiles, create a profile named for your brand (e.g. my_brand). Click Connect → Instagram and approve the OAuth flow. Meta redirects back with permission to read and publish on the linked Business account. The profile_name string you choose here is what every API request will reference — it's the only identifier you need; you do not pass IDs or social_account_id values.

2. 2

   Generate an API key

   Go to Dashboard → API Keys → Create Key. Copy the key value the moment it's shown — CodivUpload stores only the SHA-256 hash and you cannot retrieve the plaintext later. Treat it like a password: store it in your secret manager, your platform's env vars (Vercel, Render, Fly), or a vault like 1Password Secrets Automation.

3. 3

   Schedule a Reel via POST /v1/posts

   Send a POST with post_type=video, profile_name pointing at your profile, platforms=["instagram"], a single video URL inside media_urls, and scheduled_date in ISO 8601 UTC. CodivUpload validates the request, queues it inside pgmq, and the worker picks it up at the scheduled timestamp. Use Instagram-specific overrides like instagram_share_to_feed (Reels also appear on the main feed) and instagram_cover_url (custom cover frame) namespaced with instagram_.

   curl -X POST https://api.codivupload.com/v1/posts \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "post_type": "video",
       "profile_name": "my_brand",
       "platforms": ["instagram"],
       "media_urls": ["https://your-cdn.example.com/reel.mp4"],
       "description": "New product drop — link in bio.",
       "scheduled_date": "2026-05-10T14:00:00Z",
       "instagram_share_to_feed": true,
       "instagram_cover_url": "https://your-cdn.example.com/cover.jpg",
       "instagram_alt_text": "Hands holding the new product against a beige backdrop"
     }'

4. 4

   Schedule a carousel (multi-image post)

   Carousels accept up to 10 images on Instagram. Set post_type=image and pass each image URL inside media_urls in the order you want them displayed. CodivUpload uploads each child container to Instagram's Graph API, then creates the carousel parent and stores the published media id back in the destination row. You can override the global description specifically for Instagram with the instagram_alt_text field, which Instagram uses for accessibility and image search.

   curl -X POST https://api.codivupload.com/v1/posts \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "post_type": "image",
       "profile_name": "my_brand",
       "platforms": ["instagram"],
       "media_urls": [
         "https://your-cdn.example.com/photo-1.jpg",
         "https://your-cdn.example.com/photo-2.jpg",
         "https://your-cdn.example.com/photo-3.jpg"
       ],
       "description": "Behind the scenes from our latest shoot 📸",
       "instagram_alt_text": "Studio setup with two softboxes and a teleprompter"
     }'

5. 5

   Apply Instagram-specific overrides

   Every Instagram-only field is namespaced with the instagram_ prefix and is ignored if instagram is not in the platforms array. The most useful ones in production are: instagram_share_to_feed (a Reel also lands on the main feed grid), instagram_cover_url (custom Reel cover image), instagram_alt_text (accessibility text used by screen readers and image search), instagram_collaborators (an array of usernames to invite as collaborators), instagram_location_id (geotag the post to a Meta-known location), and instagram_media_urls (override the global media_urls just for Instagram — useful when you need a vertical version for IG and a square one for X).

6. 6

   Verify the result with GET /v1/posts/:id

   After scheduling, the response returns post_id and destinations_count. Poll GET /v1/posts/:id (or wire up a webhook subscription via /v1/webhooks) to track status. The lifecycle is scheduled → publishing → completed (or partially_failed / failed if a destination errored). The response includes a destinations array with one row per platform, each containing status, post_url (set after success), and error_message (set after failure).

   curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.codivupload.com/v1/posts/POST_ID
   
   # Response:
   # {
   #   "post": {
   #     "id": "...",
   #     "status": "completed",
   #     ...
   #   },
   #   "destinations": [
   #     {
   #       "platform": "instagram",
   #       "status": "success",
   #       "post_url": "https://www.instagram.com/p/ABC123/"
   #     }
   #   ]
   # }

Frequently asked