API docs

API documentation

Generate branded Instagram carousels programmatically. Create an API key, enqueue a generation against one of your profiles, poll until it's done, and download a ZIP of the rendered PNG slides.

Who it is for. API access is included on Pro and above. Free and Starter accounts cannot create a key or generate through it, and are told which plan they need. Generations made through the API draw on the same monthly allowance as the dashboard.

Availability. The v1 endpoints are behind a feature flag that is currently off for this deployment, so this reference is published ahead of the rollout and keys will not authenticate against it until we switch it on. Everything below is the shape it will have when we do.

Base URL

All endpoints are relative to https://instamaker.ai/api/v1. Request bodies and responses are JSON, unless noted otherwise.

https://instamaker.ai/api/v1

1. Create an API key

API keys are managed with your session JWT. Accounts are issued during early access: to request one, email sales@instamaker.ai. With an account, get a token programmatically:

Sign in
curl -X POST https://instamaker.ai/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-password"}'

Then create a key. The response contains the raw key exactly once — keys are stored hashed and cannot be recovered afterwards, so save it somewhere safe.

Create a key
curl -X POST https://instamaker.ai/api/v1/api-keys \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"name": "ci-runner"}'
Response — 201 Created
{
  "id": "9f1c2d3e-4b5a-...",
  "name": "ci-runner",
  "key": "im_7z8k...",
  "key_prefix": "im_7z8k...",
  "created_at": "2026-08-16T12:00:00Z"
}

2. Create a generation

Enqueue a generation for one of your profiles. The profile must be owned by the key's user and have at least 7 themes configured. template_id is optional — pass it to apply a saved template as a design override.

Enqueue a generation
curl -X POST https://instamaker.ai/api/v1/generations \
  -H "X-API-Key: im_7z8k..." \
  -H "Content-Type: application/json" \
  -d '{"profile_id": "3f2a4b5c-6d7e-...", "template_id": null}'
Response — 202 Accepted
{
  "id": "c1d2e3f4-5a6b-...",
  "status": "pending",
  "format": "square",
  "source_language": "en",
  "languages": ["en", "es"],
  "topic": null,
  "slug": null,
  "error_message": null,
  "outputs": [],
  "images": [],
  "created_at": "2026-08-16T12:05:00Z",
  "started_at": null,
  "completed_at": null,
  "result_url": null
}

Generation runs asynchronously on our workers — it can take 30–90 seconds. The response is a pending job with result_url: null.

3. Poll for status

Poll the job until status is completed — the status changes from pending to processing while the worker runs, then completed (or failed with an error_message).

Poll status
curl -H "X-API-Key: im_7z8k..." \
  https://instamaker.ai/api/v1/generations/c1d2e3f4-5a6b-...
Response — 200 OK
{
  "id": "c1d2e3f4-5a6b-...",
  "status": "completed",
  "completed_at": "2026-08-16T12:06:30Z",
  "result_url": "https://instamaker.ai/api/v1/generations/c1d2e3f4-5a6b-.../download",
  "outputs": ["..."],
  "images": ["..."]
}

4. Download the result

Once completed, download the ZIP of rendered slides — one PNG per slide. Returns 404 until the generation is completed.

Download
curl -o carousel.zip -H "X-API-Key: im_7z8k..." \
  https://instamaker.ai/api/v1/generations/c1d2e3f4-5a6b-.../download

Publishing & scheduling

Beyond the download-and-upload workflow above, Instamaker can push a finished carousel straight to your social channels. Connect an account once with each platform's OAuth consent screen — no token copy-pasting — then post or schedule from the dashboard.

  • Connect once: Instagram Business, Facebook Pages, TikTok, LinkedIn, Pinterest, X, and Bluesky share the same OAuth connect flow. Bluesky instead takes a handle + app password inline (no OAuth), and a Webhook platform posts a JSON payload to a URL you configure — the integration point for Zapier, n8n, or Slack.
  • One post, many channels: send one carousel to any mix of connected accounts in a single action, with an optional shared schedule and per-channel caption overrides.
  • Profile publish groups: each niche profile remembers a default set of channels, so posting for that profile targets them automatically — override per post anytime.
  • Schedule & cancel: pick a time per channel; cancel any queued or scheduled post before it publishes. Post status and the platform post URL are recorded per job.

Availability, stated plainly: publishing is built but not switched on for this deployment yet, so the Publish section of the dashboard will tell you the same thing. Until then the workflow is the one documented above — download the PNGs and post them yourself.

Connecting Instagram and Facebook requires a Meta app with the content-publishing permissions reviewed; TikTok requires the Content Posting API audit; Pinterest requires Pinterest app review; X is a paid API (~$0.01/post). Platform constraints are surfaced honestly in the UI — for example LinkedIn's organic API delivers multi-image posts, not carousel cards, and X caps a post at four images. Programmatic publishing via API key is on the roadmap.

Error codes & limits →