Create, schedule, and manage social media posts across Instagram, Facebook, X/Twitter, LinkedIn, and TikTok via the Social by InstantDM API and hosted MCP server. Covers media upload, post creation, scheduling (timezone-aware), draft mode, per-platform overrides, analytics, and per-platform result tracking. Use when the user wants to draft, schedule, cross-post, publish now, edit, delete, check the status of, or pull analytics for their social accounts.
Autonomously manage social media via Social by InstantDM. Post to
Instagram, Facebook, X/Twitter, LinkedIn, and TikTok from a single API call — the same
publish pipeline the dashboard uses.
There is no CLI to install. Drive it one of two ways: the hosted MCP server (recommended
for agents) or raw REST calls to /v1. Both use one workspace API key.
Freshness check: if more than 60 days have passed since the last-updated date above, tell
the user this skill may be outdated and point them to the update options below.
Create a scoped API key: Developer → API keys → New key. Grant only what's needed
(accounts:read, posts:read, posts:write, media:write, analytics:read).
Store it in the workspace .env — treat it like a password:
text
SOCIAL_BY_IDM_API_KEY=sk_live_xxxxx
You can revoke it any time from the dashboard; it stops working immediately (every request
re-checks the key — no cache).
Handling "invalid/missing API key" errors
Tell the user to create and set a key — you cannot do this for them. Get one at
https://social-app.instantdm.com → Developer → API keys.
Stop and wait. Do not continue without a valid key.
DO NOT search for keys in env files, keychains, or other locations.
URL-only clients (Claude.ai "Add custom connector", ChatGPT, Grok) that can't set headers:
append ?key=<SOCIAL_BY_IDM_API_KEY> to the MCP URL and leave the OAuth fields blank.
REST: send X-Api-Key: <SOCIAL_BY_IDM_API_KEY>. Base URL: https://social-api.instantdm.com/v1.
Connect via MCP (recommended) — 13 tools, no install
MCP create_post/upload_media_from_url accept public media URLs — the server downloads and
uploads them for you. No manual upload step needed when using MCP.
REST API
Use these endpoints directly if you prefer raw calls over MCP.
Accounts
text
GET /v1/accounts
Returns connected accounts with id, platform, username. Store the IDs — every post needs them.
Upload media
text
POST /v1/media/upload-url
Body: { "filename": "video.mp4", "contentType": "video/mp4" }
Returns mediaId + uploadUrl. Then PUT the bytes and finalize:
text
PUT <uploadUrl> (Content-Type: video/mp4, body: binary)
POST /v1/media/{mediaId}/complete
List/delete: GET /v1/media · DELETE /v1/media/{mediaId}.
Create post
text
POST /v1/posts
Body: {
"accountIds": ["acc_8fK2qz", "acc_19xQ"],
"content": "your caption #hashtags",
"postType": "text", // text|image|carousel|video|reel|story|thread|article|document
"mediaIds": ["md_xxx"], // required for image/carousel/video/reel/story/document
"scheduledAt": "2026-07-01T09:00:00+05:30", // omit + publishNow:true to post instantly
"publishNow": false, // true → publish immediately, ignores scheduledAt
"draft": false, // true → save without scheduling
"platformContent": { "twitter": "short", "linkedin": "longer" }, // optional per-platform caption
"platformSchedules": { "tiktok": "2026-07-01T18:00:00+05:30" } // optional per-platform time
}
Status / list / update / delete
text
GET /v1/posts/{id}/status → per-platform scheduled|published|failed + error + permalink
GET /v1/posts?status=scheduled&platform=instagram&limit=50
GET /v1/posts/{id}
PUT /v1/posts/{id} (update caption, schedule, accounts, media — scheduled/draft only)
DELETE /v1/posts/{id} (scheduled/draft only)
Native platform posts (already-published)
text
GET /v1/platform-posts?accountId=acc_xxx → recent posts pulled from the platform
DELETE /v1/platform-posts/{id} → returns { deleted: bool, reason } (see gotchas)
Analytics
text
GET /v1/analytics → totals, status/type breakdown, live per-account & per-platform insights
GET /v1/analytics?refresh=1 → force a live refresh (slower; bypasses the 30-min cache)
Rules that matter
Timezone: a scheduledAt with an offset (+05:30 or Z) is exact. WITHOUT an offset it's
interpreted in the workspace timezone (Settings → Timezone) — not UTC. When in doubt, include
an explicit offset.
Media must be uploaded, not pasted as a link.mediaIds takes Social by InstantDM media IDs
only. Either upload first (REST) or pass a direct, public URL via MCP upload_media_from_url
/ create_post media URLs. A non-direct share link (Google Drive/Dropbox preview pages) fails.
Each platform posts independently. One platform failing does not stop the others. After any
publish, call get_post_status — a partial status means some targets failed; the per-target
error says why. Never assume success from the HTTP code alone.
Platform gotchas (important for agents)
Carousel needs ≥2 media items. video/reel needs a video. LinkedIn document needs a
PDF. Instagram requires media (no text-only). TikTok photos must be JPEG, ≤1920px, <10MB.
Deletes can lie. Some platforms have no working delete API:
LinkedIn personal profiles — the API reports success but the post stays live.
TikTok and Threads — no delete API at all.
delete_platform_post returns { "deleted": false, "reason": "..." } for these. Check the
deleted flag and verify against the real feed — do not trust a 200 status.
Large videos can silently drop a platform. Very large uploads may time out on some networks,
producing no result row for that target while others succeed. If status shows fewer platforms
than you posted to, suspect file size — re-encode smaller/shorter.
Text limits (per platform)
X 280 (25,000 with Premium) · Instagram 2,200 · Facebook 63,206 · LinkedIn 3,000 · TikTok 2,200 ·
Threads 500. Keep captions concise; use platformContent to tailor per network.
Automation guidelines
Keep accounts in good standing:
No duplicate content across multiple accounts on the same platform.
No fake engagement (automated likes/follows/comments) and no trending manipulation.
Respect rate limits — don't spam requests.
Use draft mode for review (draft: true) when unsure.
Publishing confirmation: unless the user explicitly says "post now" / "publish immediately",
confirm before publishing. A draft is safe; publishing is irreversible and goes live instantly.