Posts batch

POST /posts/batch builds a content calendar in one call, for example a full month drafted by an AI agent, instead of calling POST /posts in a loop. It backs the MCP tool create_posts_batch.

Required scope: posts:write.

Endpoint

Request parameters

curl -X POST https://api.getimma.com/v1/posts/batch \
  -H "Authorization: Bearer imma_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6b1a9c4e-2f3d-4e5f-8a9b-6b1a9c4e2f3d" \
  -d '{
    "profile_id": "prof_01J...",
    "items": [
      { "caption": "...", "media": ["med_1"], "targets": [{ "account_id": "acc_ig_..." }],
        "scheduled_at": "2026-10-01T18:30:00+07:00", "approval": { "mode": "link" }, "ai_generated": true },
      { "caption": "...", "media": ["med_2"], "targets": [{ "account_id": "acc_tt_...", "tiktok": { "mode": "direct" } }],
        "scheduled_at": "2026-10-02T18:30:00+07:00", "approval": { "mode": "link" }, "ai_generated": true }
    ]
  }'

Response (207 multi-status):

{
  "results": [
    { "index": 0, "status": "awaiting_approval", "id": "post_01J...",
      "approval": { "url": "https://getimma.com/approve/..." } },
    { "index": 1, "status": "error",
      "error": { "code": "quota_exceeded_for_day", "message": "TikTok daily quota is full for 2026-10-02." } }
  ]
}

How it behaves

• Up to 31 items per call, sized for one calendar month while staying light enough to validate synchronously in one request.
• Each item is validated and processed independently: one item failing (for example media not yet ready) does not cancel the others.
• Idempotency-Key applies per item, using the request's key combined with the item's index, so a retried call that partially failed can be corrected without duplicating items that already succeeded.
• A TikTok target in any item always goes through hosted approval or inbox mode, exactly like a single POST /posts call. There is no batch path that bypasses consent.
• Platform quota (Instagram 100, Threads 250, TikTok around 15/day) is checked per target day from each item's scheduled_at, not just against the whole batch's total, so one full day does not reject the rest of the month.

Errors

Batch-level errors (bad request shape, auth, idempotency conflict) use the same codes as Posts and Errors. Per-item failures appear inside results[].error with the same shape and do not fail the whole call; the most common per-item code is quota_exceeded_for_day.

Platform notes

Use Calendar first to see what is already scheduled before calling this endpoint, so a new batch does not collide with existing slots. See Platform rules for TikTok consent and per-platform posting limits, which apply identically here as they do to a single post.