blotato

Blotato Publisher

Publish and schedule social-media posts across X/Twitter, TikTok, Instagram, LinkedIn, YouTube, Facebook, Threads, Pinterest, Bluesky and more — via REST API or the Blotato MCP server. Designed for high-volume launches where browser-based tools (Postiz, Buffer) hit their per-platform UI rate limits.

When to use

Scheduling 5+ posts across 2+ platforms in one batch
Publishing the same media (video, image, carousel) to TikTok + X + Instagram + Threads simultaneously
Building a multi-day launch campaign (e.g., 13-day product-launch cadence)
When Postiz / Buffer / native UIs are blocked, rate-limited, or unsupported for the target account
When the user has already connected accounts at https://www.blotato.com/dashboard and has an API key

When NOT to use

Single one-off post that the user can publish manually in 30 seconds
Replying to specific tweets / engagement workflows (Blotato is for posting, not engaging — use platform-specific tools or browser automation)
When the user explicitly asks to use a different tool (e.g., "use Postiz only")

Setup (one-time)

Sign up at https://www.blotato.com/ — create a Blotato account.
Connect social accounts at https://www.blotato.com/dashboard → Accounts → add X, TikTok, Instagram, LinkedIn, etc. Authorize each one. Blotato handles the OAuth flow per platform.
Get API key: https://www.blotato.com/dashboard → Settings → API → Generate key. Copy it (format: blt_<base64>=).
Store the key in the user's secrets vault. Recommended path: ~/.zshrc or .env:
```
export BLOTATO_API_KEY='blt_xxxxxxxxxxxxxxxxxxxxxxxx='
```
Verify by calling list accounts (see below). The response should include every connected platform with its accountId.

Two integration modes

Mode A — REST API (recommended for batch work, scripts, CI/CD)

Base URL: https://backend.blotato.com/v2 Auth header: blotato-api-key: $BLOTATO_API_KEY Content-Type: application/json

⚠️ DNS gotcha (April 2026 onward): backend.blotato.com sometimes fails to resolve via public DNS resolvers. The actual host is on Heroku. Workaround:
IP=$(dig +short A blooming-garbanzo-gikc58n9n0a3rgn28l96fwwu.herokudns.com | head -1)
curl ... --resolve "backend.blotato.com:443:$IP"
Re-resolve at the start of every batch — Heroku IPs rotate.

Mode B — MCP server (recommended for chat-style interactive use)

Add to ~/.claude/mcp.json:

{
  "mcpServers": {
    "blotato": {
      "type": "http",
      "url": "https://mcp.blotato.com/mcp",
      "headers": { "blotato-api-key": "$BLOTATO_API_KEY" }
    }
  }
}

Tools exposed:

blotato_list_accounts — get every connected social account
blotato_upload_media — upload an image/video, returns a Blotato-hosted media URL
blotato_create_post — schedule or publish immediately
blotato_get_post_status — poll until scheduled / published / failed

Core workflow

1. LIST ACCOUNTS   → get the accountId for each platform you want to post to
2. UPLOAD MEDIA    → if posting video/image, upload to Blotato storage first
3. CREATE POST     → schedule each post (or fire immediately by omitting scheduledTime)
4. VERIFY          → list posts and confirm scheduled state + correct time

Step 1 — List accounts

IP=$(dig +short A blooming-garbanzo-gikc58n9n0a3rgn28l96fwwu.herokudns.com | head -1)
curl -sS "https://backend.blotato.com/v2/accounts" \
  -H "blotato-api-key: $BLOTATO_API_KEY" \
  --resolve "backend.blotato.com:443:$IP" | jq

Response shape:

{
  "accounts": [
    { "id": "44288", "platform": "tiktok", "handle": "wc26net", "active": true },
    { "id": "19294", "platform": "twitter", "handle": "wc26net", "active": true },
    { "id": "18001", "platform": "twitter", "handle": "aabyzov", "active": true }
  ]
}

Always cache the id per platform/handle in a constants block at the top of your batch script. Account IDs are stable.

Step 2 — Upload media (optional)

If you already have a public CDN URL (S3, Cloudflare R2, Postiz CDN, etc.), skip this step and use the public URL directly in mediaUrls.

If your media is local-only:

curl -sS -X POST "https://backend.blotato.com/v2/media" \
  -H "blotato-api-key: $BLOTATO_API_KEY" \
  --resolve "backend.blotato.com:443:$IP" \
  -F "file=@/path/to/video.mp4"

Response includes {"mediaUrl": "https://database.blotato.io/storage/v1/object/public/public_media/<owner>/<uuid>.mp4"} — use that string in mediaUrls.

Step 3 — Create a post

X / Twitter

curl -sS -X POST "https://backend.blotato.com/v2/posts" \
  -H "blotato-api-key: $BLOTATO_API_KEY" \
  -H "Content-Type: application/json" \
  --resolve "backend.blotato.com:443:$IP" \
  -d '{
    "post": {
      "accountId": "19294",
      "content": {
        "platform": "twitter",
        "text": "13 days until kickoff.\n\nwc-26.net",
        "mediaUrls": ["https://database.blotato.io/storage/.../launch.mp4"]
      },
      "target": { "targetType": "twitter" }
    },
    "scheduledTime": "2026-05-29T15:00:00Z"
  }'

TikTok (richer target object)

curl -sS -X POST "https://backend.blotato.com/v2/posts" \
  -H "blotato-api-key: $BLOTATO_API_KEY" \
  -H "Content-Type: application/json" \
  --resolve "backend.blotato.com:443:$IP" \
  -d '{
    "post": {
      "accountId": "44288",
      "content": {
        "platform": "tiktok",
        "text": "13 days. 48 teams. 16 cities.\n\nwc-26.net 👇\n\n#WorldCup2026 #fyp",
        "mediaUrls": ["https://database.blotato.io/storage/.../launch.mp4"]
      },
      "target": {
        "targetType": "tiktok",
        "privacyLevel": "PUBLIC_TO_EVERYONE",
        "disabledComments": false,
        "disabledDuet": false,
        "disabledStitch": false,
        "isBrandedContent": false,
        "isYourBrand": true,
        "isAiGenerated": false
      }
    },
    "scheduledTime": "2026-05-29T13:00:00Z"
  }'

Critical TikTok flags: isYourBrand: true is required for first-party brand accounts. isAiGenerated: true MUST be set when the video was AI-generated (Veo / Kling / Higgsfield / Sora / Kie.ai) — TikTok now enforces AI-content labels per their policy. Misclassifying gets accounts shadowbanned.

Instagram (standalone)

{
  "post": {
    "accountId": "<ig_account_id>",
    "content": {
      "platform": "instagram",
      "text": "13 days until WC26. ⚽🌎",
      "mediaUrls": ["https://.../launch.mp4"]
    },
    "target": { "targetType": "instagram", "postType": "post" }
  },
  "scheduledTime": "2026-05-29T16:00:00Z"
}

Valid postType values for Instagram-standalone: "post", "story". Do not use "reel" — Blotato will reject. For Reels, use Instagram-via-Facebook-Business connection.

Common pitfalls (debugged in production)

Issue	Fix
`text` contains newlines / quotes	JSON-escape: `$(jq -Rs . <<<"$text")` in bash
Schedule fires immediately	Always include `scheduledTime` in ISO 8601 UTC format with trailing `Z`
401 unauthorized	Check header name: `blotato-api-key` (kebab-case, lowercase)
Post creates but never publishes	Check the account is still authorized in dashboard — Blotato silently disables expired OAuth tokens
DNS resolution fails	Use `--resolve` workaround above

Step 4 — Verify queue

curl -sS "https://backend.blotato.com/v2/posts?limit=100" \
  -H "blotato-api-key: $BLOTATO_API_KEY" \
  --resolve "backend.blotato.com:443:$IP" | \
  jq -r '.items[] | select(.state.type=="scheduled") |
    "\(.postTime[0:16]) | \(.platform | .[0:2] | ascii_upcase) | \(.text | .[0:80] | gsub("\n";" "))"'

Response schema gotcha: the queue endpoint returns {"items": [...], "cursor": "..."}, not {"posts": [...]}. The cursor is a base64-encoded continuation token for pagination — pass it as ?cursor= to get the next page. Iterate until cursor is empty/null.

Batch scheduling pattern (production-tested)

For multi-day campaigns, structure your script as a single bash file with helper functions:

#!/bin/bash
set -e
export BLOTATO_API_KEY='blt_...'
IP=$(dig +short A blooming-garbanzo-gikc58n9n0a3rgn28l96fwwu.herokudns.com | head -1)
MEDIA="https://database.blotato.io/storage/.../launch.mp4"
TT_ACCOUNT=44288   # TikTok @wc26net
X_ACCOUNT=19294    # X @wc26net

post_tt() {
  curl -sS -X POST "https://backend.blotato.com/v2/posts" \
    -H "blotato-api-key: $BLOTATO_API_KEY" -H "Content-Type: application/json" \
    --resolve "backend.blotato.com:443:$IP" \
    -d "{\"post\":{\"accountId\":\"$1\",\"content\":{\"platform\":\"tiktok\",\"text\":$(jq -Rs . <<<"$2"),\"mediaUrls\":[\"$MEDIA\"]},\"target\":{\"targetType\":\"tiktok\",\"privacyLevel\":\"PUBLIC_TO_EVERYONE\",\"disabledComments\":false,\"disabledDuet\":false,\"disabledStitch\":false,\"isBrandedContent\":false,\"isYourBrand\":true,\"isAiGenerated\":false}},\"scheduledTime\":\"$3\"}" \
    | jq -r '.postSubmissionId // .error'
}

post_x() {
  curl -sS -X POST "https://backend.blotato.com/v2/posts" \
    -H "blotato-api-key: $BLOTATO_API_KEY" -H "Content-Type: application/json" \
    --resolve "backend.blotato.com:443:$IP" \
    -d "{\"post\":{\"accountId\":\"$1\",\"content\":{\"platform\":\"twitter\",\"text\":$(jq -Rs . <<<"$2"),\"mediaUrls\":[\"$MEDIA\"]},\"target\":{\"targetType\":\"twitter\"}},\"scheduledTime\":\"$3\"}" \
    | jq -r '.postSubmissionId // .error'
}

# Day 1 cadence
post_tt $TT_ACCOUNT "13 days. 48 teams. 16 cities."  "2026-05-29T13:00:00Z"
post_x  $X_ACCOUNT  "13 days until FIFA World Cup."  "2026-05-29T15:00:00Z"

# ... continue for each day ...

This pattern scales to 50+ posts per script. Every successful create returns a postSubmissionId — log these so you can match server-side state back to your local plan.

Algorithm-aware cadence (per platform)

Platform	Daily cap	Best-time UTC	Notes
TikTok	3/day max	13:00, 16:00, 22:00	FIFA's official Preferred Platform. Highest 3-second-retention algorithm. AI-content label MUST be honest.
X / Twitter	4–6/day	13:00, 15:00, 19:00, 22:00	Replies > standalone posts for organic reach. Don't stack same-content across times.
Instagram-standalone	2/day	14:00, 17:00	Reels surface to non-followers more than feed posts.
LinkedIn	1/day	13:00 Tue/Wed/Thu	Founder voice beats brand voice 5×.
Threads	3–5/day	14:00, 19:00	Algorithm rewards reply-density.
Facebook Page	1–2/day	14:00, 18:00	Older demographic; better paid-ad target than organic.
YouTube Shorts	1–2/day	23:00 (US peak)	Longest tail; SEO matters.

Never paste the same caption across platforms. The algorithms penalize obvious cross-posts. Adapt: shorter for X, hashtags for IG/TikTok, no hashtags for LinkedIn, conversational for Threads.

Verification & telemetry

After scheduling a batch, dump the queue to a file and diff against your plan:

curl -sS "https://backend.blotato.com/v2/posts?limit=100" \
  -H "blotato-api-key: $BLOTATO_API_KEY" \
  --resolve "backend.blotato.com:443:$IP" > /tmp/blotato-queue.json

# Count scheduled by platform
jq -r '[.items[] | select(.state.type=="scheduled")] | group_by(.platform) | .[] | "\(.[0].platform): \(length)"' /tmp/blotato-queue.json

The web dashboard view of scheduled posts is at: https://www.blotato.com/dashboard → Posts → Scheduled tab.

https://my.blotato.com/scheduled is NOT a valid URL — returns 404. Always use www.blotato.com/dashboard as the canonical entry point.

Failure modes & escalation

Symptom	Likely cause	Fix
HTTP 401 on every call	Wrong auth header name or expired key	Use `blotato-api-key:` (NOT `Authorization: Bearer`). Regenerate key in dashboard.
HTTP 522 / SSL error	Heroku DNS rotation	Re-run `dig +short A blooming-garbanzo-gikc58n9n0a3rgn28l96fwwu.herokudns.com` and update `--resolve`.
Post scheduled but never publishes	Account OAuth expired	Open `www.blotato.com/dashboard` → Accounts → re-authorize the disconnected platform.
TikTok post fails with content-policy error	Missing `isAiGenerated` or incorrect `privacyLevel`	Add `"isAiGenerated": true` if applicable; valid privacy: `PUBLIC_TO_EVERYONE`, `MUTUAL_FOLLOW_FRIENDS`, `FOLLOWER_OF_CREATOR`, `SELF_ONLY`.
Instagram fails with "post_type invalid"	Tried `"reel"` on standalone IG	Use `"post"` or connect IG via Facebook Business for reels.
`mediaUrls` rejected	URL not publicly accessible	Upload via `/v2/media` first OR use a public CDN (R2, S3, Cloudflare).

Quotas & limits (as of May 2026)

Free tier: 10 posts/month, 1 account per platform
Creator ($29/mo): 200 posts/month, 5 accounts per platform
Agency ($99/mo): 1000 posts/month, unlimited accounts
API rate limit: 60 requests/minute (across all endpoints)
Max media size: 500 MB (video), 25 MB (image)
Max video duration: 10 minutes (platform-specific limits apply downstream — TikTok 10min, X 2:20, IG Reels 90s)

Hitting the rate limit returns 429 Too Many Requests with a Retry-After header. Respect it; don't hammer.

Requirements

Blotato account at https://www.blotato.com/ (free tier works for small launches)
API key in $BLOTATO_API_KEY
curl + jq for the REST flow (every modern dev box has both)
dig for the DNS workaround (macOS / Linux native)
Publicly accessible media (CDN URL or Blotato /v2/media upload)

Related skills

social-media-posting (this plugin) — broader cross-platform orchestrator with image generation
social-posts (this plugin) — copywriting + Chrome-based interactive posting
slack-messaging (this plugin) — Slack-specific session boundaries

Use Blotato when you have already drafted content and need reliable batch scheduling. Use social-media-posting when you need the full draft → image → review → post loop.

Quick reference — every operation in one block

# 0. Setup
export BLOTATO_API_KEY='blt_...'
IP=$(dig +short A blooming-garbanzo-gikc58n9n0a3rgn28l96fwwu.herokudns.com | head -1)
HDR="-H blotato-api-key:$BLOTATO_API_KEY"
RES="--resolve backend.blotato.com:443:$IP"
BASE="https://backend.blotato.com/v2"

# 1. List accounts
curl -sS $HDR $RES "$BASE/accounts" | jq '.accounts[] | {id, platform, handle}'

# 2. Upload media (only if no public CDN URL)
curl -sS $HDR $RES -X POST "$BASE/media" -F file=@./launch.mp4 | jq -r '.mediaUrl'

# 3. Create post (X example)
curl -sS $HDR $RES -X POST "$BASE/posts" \
  -H "Content-Type: application/json" \
  -d '{"post":{"accountId":"19294","content":{"platform":"twitter","text":"hello world","mediaUrls":[]},"target":{"targetType":"twitter"}},"scheduledTime":"2026-06-01T15:00:00Z"}' \
  | jq -r '.postSubmissionId'

# 4. List queue
curl -sS $HDR $RES "$BASE/posts?limit=50" | \
  jq -r '.items[] | select(.state.type=="scheduled") | "\(.postTime[0:16]) \(.platform) \(.text[0:60])"'

# 5. Delete (cancel) a scheduled post
curl -sS $HDR $RES -X DELETE "$BASE/posts/<postId>"