Instagram Auto-Poster Blueprint

NOTE

Use this page as a prompt reference. Every file below is built to be handed straight to an AI. Download it, drop it into Claude, ChatGPT, Cursor, or Lovable, and say "use this as my playbook." The prompts on this page are copy-paste ready.

NOTE

Scope of this blueprint: single-image feed posts to your own account, which is 90% of what people pay schedulers for. Reels, Stories, and carousels use the same container flow with different params; I cover the differences in section 4 so you can extend the script yourself.

WATCH OUT

Everything API-specific here was verified against Meta's docs in July 2026 against version v25.0. The old Instagram Basic Display API is fully dead (deprecated Dec 4, 2024, all requests error). If a tutorial mentions Basic Display, or uses the old truncated scope names like business_content_publish (deprecated Jan 27, 2025), it's outdated; close the tab.

PAYOFF

No App Review needed. In Development mode with Standard Access, publishing works for any account with an app role (admin, developer, or tester). You're one business posting to your own account, so Standard Access is all you'll ever need. App Review, screencasts, privacy policies, Business Verification, the 2 to 6 week wait: all of that is only for apps serving other people's accounts.

curl -X POST https://api.instagram.com/oauth/access_token \
  -F client_id=IG_APP_ID_HERE \
  -F client_secret=IG_APP_SECRET_HERE \
  -F grant_type=authorization_code \
  -F redirect_uri=YOUR_REDIRECT_URI \
  -F code=CODE_FROM_OAUTH_REDIRECT
# Returns: { "access_token": "...", "user_id": ... }  (valid ~1 hour)

curl "https://graph.instagram.com/access_token?grant_type=ig_exchange_token&client_secret=IG_APP_SECRET_HERE&access_token=SHORT_LIVED_TOKEN"
# Returns: { "access_token": "...", "token_type": "bearer", "expires_in": 5183944 }
# expires_in is just under 60 days. This is the token your scripts use.

curl "https://graph.instagram.com/refresh_access_token?grant_type=ig_refresh_token&access_token=CURRENT_LONG_LIVED_TOKEN"
# Returns: { "access_token": "...", "token_type": "bearer", "expires_in": 5184000 }
# Store the NEW token. The refresh is stateful: next refresh uses this one.

# Every Monday 08:00. Weekly is 8x more often than needed, which is the point.
0 8 * * 1 cd /home/you/ig-poster && /usr/bin/env node token-refresh.mjs >> token.log 2>&1

WATCH OUT

A dead token cannot be refreshed. If you let it expire, the refresh endpoint won't revive it; you redo the full OAuth flow from section 2 and re-seed. This is why the script alerts on refresh failure instead of failing quietly: the alert arrives while the old token still has days left.

WATCH OUT

Images are JPEG only. PNG and WebP get rejected, and so do exotic JPEG variants (MPO/JPS). Feed aspect ratio must sit between 4:5 and 1.91:1, width 320 to 1440px. Outside that window you get error 36003 or 2207009. Export everything as a 1080x1350 (4:5) or 1080x1080 JPEG and you never think about this again.

WATCH OUT

The URL must be publicly fetchable by a robot. Meta fetches image_url server-side at container creation. CDN auth, signed URLs that expire, redirects, or bot-blocking (Cloudflare "verify you are human" on image paths) make the container silently go to ERROR with no useful message. The script pre-flights this by fetching your URL first and checking for HTTP 200 plus Content-Type: image/jpeg.

const API = "https://graph.instagram.com/v25.0";

// 1. create container
const container = await post(`${API}/${IG_USER_ID}/media`, {
  image_url: "https://yournewsletter.com/ig/today.jpg", // public JPEG, 4:5 to 1.91:1
  caption: "caption text, max 2200 chars, max 30 hashtags",
  alt_text: "what the image shows",
  access_token: TOKEN,
});

// 2. poll once per minute, max 5 (Meta's guidance), after a 10s head start
await sleep(10_000);
for (let i = 0; i < 5; i++) {
  const { status_code } = await get(`${API}/${container.id}`, {
    fields: "status_code", access_token: TOKEN,
  });
  if (status_code === "FINISHED") break;
  if (status_code === "ERROR" || status_code === "EXPIRED")
    throw new Error(`container ${status_code}: check URL, JPEG, aspect ratio`);
  await sleep(60_000);
}

// 3. publish
const media = await post(`${API}/${IG_USER_ID}/media_publish`, {
  creation_id: container.id, access_token: TOKEN,
});
console.log("live:", media.id);

You are writing a month of Instagram captions for my account. You will match MY voice, not a generic social media voice. My voice is defined by the examples below; the tone doc is a tiebreaker, the examples win any conflict.

## MY ACCOUNT
- Handle and niche: [HANDLE + ONE-LINE NICHE, e.g. "@buildlog, I document building SaaS products with AI coding agents"]
- Audience: [WHO FOLLOWS YOU AND WHY, e.g. "solo devs and indie hackers, 25-40, want to ship faster"]
- What I'm promoting this month: [PRODUCT/OFFER/NEWSLETTER + LINK LOCATION, e.g. "my newsletter, link in bio"]
- Posting cadence: [N] posts over [N] days

## MY PAST CAPTIONS (the voice source, verbatim, do not clean these up)
[PASTE 10-20 REAL CAPTIONS, EACH SEPARATED BY "---". Include your best performers AND typical ones. More is better.]

## MY TONE DOC
[PASTE YOUR TONE/STYLE DOC, OR 5 BULLETS: identity, audience, words you use, words you ban, the one feeling every post should leave]

## THIS MONTH'S CONTENT PILLARS
[LIST 3-5 PILLARS WITH ROUGH WEIGHTS, e.g.:
- 40% build-in-public updates (what I shipped, what broke, what it cost)
- 25% tactical how-tos my audience can use today
- 20% opinions/hot takes on my niche
- 15% personal/behind-the-scenes]

## RAW MATERIAL (turn these into posts)
[PASTE YOUR NOTES: wins, numbers, screenshots you plan to post, lessons, launches, anything. Bullet points are fine. The model must NOT invent facts, numbers, or events not listed here.]

## HARD RULES
1. Every caption starts with a HOOK as line 1: a claim, a number, a tension, or a question. Never a soft warm-up like "So excited to share". Line 1 must survive being the only line anyone reads (Instagram truncates after ~125 characters).
2. Rotate hook types across the month, no two consecutive posts with the same type: [NUMBER hook / CONTRARIAN hook / STORY-OPENER hook / QUESTION hook / MISTAKE-CONFESSION hook].
3. Rotate CTAs on a 4-post cycle and label each: (a) comment prompt with a specific question, (b) save/share prompt tied to the post's utility, (c) link-in-bio push for [OFFER], (d) no CTA at all, just end strong. Never two link pushes in a row.
4. Caption length: vary between 300 and 1,500 characters. Hard cap 2,200 characters including hashtags (Instagram's limit).
5. Hashtags: exactly [N, suggest 3-8] per post, niche-specific, on the last line. Never more than 30 (API rejects it). No banned or spammy tags.
6. Every fact, number, and event must come from RAW MATERIAL above. If a pillar has no raw material left, write an evergreen post for that pillar and flag it "EVERGREEN" so I can fact-check it.
7. Match my sentence length, punctuation habits, emoji usage (or absence), and line-break style from the past captions. If my captions never use emojis, use zero.
8. No engagement-bait cliches: no "double tap if", no "tag someone who", no "you won't believe".

## OUTPUT FORMAT
Return ONLY a JSON array, no prose before or after. One object per post:

[
  {
    "day": 1,
    "pillar": "build-in-public",
    "hook_type": "NUMBER",
    "cta_type": "comment",
    "caption": "full caption text with line breaks as \n, hashtags on last line",
    "image_direction": "one sentence describing the JPEG to pair with this (I shoot/design these separately)",
    "alt_text": "one-sentence accessibility description of the intended image",
    "flag": null
  }
]

"flag" is null, or "EVERGREEN" (rule 6), or "NEEDS_FACT_CHECK" if you had to interpret ambiguous raw material.

Before the JSON is generated, silently verify: hook rotation valid, CTA cycle valid, all facts traceable to raw material, zero captions over 2,200 chars. Fix violations, then output.

{
  "account": "@yourhandle",
  "posts": [
    {
      "id": "2026-07-09-build-update",
      "status": "pending",
      "image_url": "https://yournewsletter.com/ig/2026-07-09.jpg",
      "caption": "hook line first...\n\nbody...\n\n#tags #on #last #line",
      "alt_text": "what the image shows",
      "pillar": "build-in-public",
      "cta_type": "comment",
      "not_before": "2026-07-09T00:00:00Z"
    }
  ]
}

# Post daily at 09:30 (pick your audience's active hour)
30 9 * * * cd /home/you/ig-poster && /usr/bin/env node post-to-instagram.mjs >> poster.log 2>&1

# Refresh the token every Monday 08:00
0 8 * * 1 cd /home/you/ig-poster && /usr/bin/env node token-refresh.mjs >> token.log 2>&1

NOTE

Where to run the crons: any always-on box. A $4/mo VPS, a Raspberry Pi, GitHub Actions on a schedule (commit the queue back to the repo), or your homelab. One catch with Actions: the refresh script has to persist the rotated token between runs, and token.json must never be committed. Either update a repo secret from the workflow via the GitHub API, or skip the ceremony and use the VPS; a box with a disk is the simple version.

curl "https://graph.instagram.com/v25.0/IG_USER_ID_HERE/content_publishing_limit?fields=quota_usage,config&access_token=TOKEN_HERE"
# quota_usage = posts published in the current 24h window
# config.quota_total = your actual ceiling (the script checks this before every post)

PAYOFF

Ship checklist: professional account converted, Business app with Instagram product, tester invite accepted, long-lived token in token.json, both crons installed, dry-run green, queue filled with 30 posts. From here your Instagram runs itself and pings you maybe once a month. Here's the move: batch your first month of captions this weekend.

Get the next drop

Every new Vault system ships to the list first. Twice a week, free.