Social by InstantDM — social media skill

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.

Keeping this skill updated

Source: github.com/social-by-idm/agent-mode · API docs: socialbyidm.com/docs

Setup (once)

1. Create a workspace at social-app.instantdm.com.
2. Connect your social accounts (Accounts page).
3. 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).
4. Store it in the workspace .env — treat it like a password:

   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

1. 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.
2. Stop and wait. Do not continue without a valid key.
3. DO NOT search for keys in env files, keychains, or other locations.

Auth

• MCP / header clients: send X-Api-Key: <SOCIAL_BY_IDM_API_KEY>.
• 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

• URL: https://social-api.instantdm.com/mcp
• Claude Code / Cursor / other MCP clients:

  {
    "mcpServers": {
      "social-by-idm": {
        "type": "streamable-http",
        "url": "https://social-api.instantdm.com/mcp",
        "headers": { "X-Api-Key": "sk_live_xxx" }
      }
    }
  }
  

MCP tools (13): list_accounts, create_post, update_post, get_post, get_post_status, list_posts, delete_post, list_platform_posts, delete_platform_post, upload_media_from_url, list_media, delete_media, get_analytics.

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

GET /v1/accounts

Returns connected accounts with id, platform, username. Store the IDs — every post needs them.

Upload media

POST /v1/media/upload-url
Body: { "filename": "video.mp4", "contentType": "video/mp4" }

Returns mediaId + uploadUrl. Then PUT the bytes and finalize:

PUT <uploadUrl>        (Content-Type: video/mp4, body: binary)
POST /v1/media/{mediaId}/complete

List/delete: GET /v1/media · DELETE /v1/media/{mediaId}.

Create post

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

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)

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

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.

Platform names (exact, for filters & overrides)

instagram · facebook · twitter (X) · linkedin · tiktok

Examples

Schedule a carousel to Instagram + LinkedIn for tomorrow 9am IST:

POST /v1/posts
{ "accountIds": ["acc_ig","acc_li"], "postType": "carousel",
  "mediaIds": ["md_1","md_2","md_3"], "content": "3 lessons from this week",
  "scheduledAt": "2026-07-02T09:00:00+05:30" }

Publish a text post to X right now:

POST /v1/posts
{ "accountIds": ["acc_x"], "content": "shipping.", "publishNow": true }

Docs

• API reference: https://socialbyidm.com/docs
• MCP server + tools: https://socialbyidm.com/mcp
• Agents overview: https://socialbyidm.com/agents