Create, schedule, and manage social media posts across Instagram, TikTok, YouTube, X, LinkedIn, Facebook, Pinterest, Threads, and Bluesky via the Post Bridge API. Covers media upload, post creation, scheduling, platform-specific configs, draft mode, analytics, and post result tracking.
What this skill does to your system and your accounts. Read before
installing.
Publishes to your real social accounts. Anything it posts is live. Ask
for confirmation before creating or scheduling a post unless the user has
explicitly said not to, and prefer draft: true when intent is unclear.
Sends your media and captions to a third party. Files, captions, account
ids and scheduling metadata go to api.post-bridge.com under your API key.
Uses an API key from POST_BRIDGE_API_KEY, ./.post-bridge/config.json
or ~/.config/post-bridge/config.json. Only use a key you are willing to
let an agent post through.
Runs local commands when following the optional video workflow below,
including ffmpeg on your files.
Can move local files if you follow the optional posted/ convention,
and can create scheduled jobs if you follow the optional cron step. Both
are suggestions, not requirements. Neither happens unless you ask for it.
Autonomously manage social media posting via Post Bridge API. Post to 9 platforms from a single command or API call.
The CLI is published on npm as postbridge-cli — run it with npx postbridge-cli <command> (no install needed; npx fetches it on first use). Requires Node.js 18+. If npx postbridge-cli is unavailable for any reason, fall back to the bundled script at <skill-path>/scripts/post-bridge.js (same commands and flags).
Freshness check: If more than 30 days have passed since the last-updated date above, inform the user that this skill may be outdated and point them to the update options below.
Note for agents: Prefer npx postbridge-cli (the published npm CLI). If the skill is installed locally and you want to run the bundled copy instead, the script lives at <skill-path>/scripts/post-bridge.js — same commands and flags.
CLI Commands
Command
Description
npx postbridge-cli setup --key <key>
Configure API key
npx postbridge-cli accounts
List connected social accounts
npx postbridge-cli post --caption "..." --accounts 1,2,3
Create a post
npx postbridge-cli post --caption "..." --accounts 1,2,3 --schedule "2026-06-20T09:00:00Z"
Schedule a post for a specific time (UTC)
npx postbridge-cli post --caption "..." --accounts 1,2 --use-queue
Auto-schedule to the next queue slot (saved timezone)
npx postbridge-cli post --caption "..." --accounts 1,2 --use-queue --queue-timezone "America/New_York"
Auto-schedule to next queue slot in a specific timezone
npx postbridge-cli post --caption "..." --accounts 1,2 --draft
Save as a draft instead of publishing
npx postbridge-cli post --caption "..." --accounts 1,2 --platform-config '{"tiktok":{"draft":true}}'
Post with per-platform options
npx postbridge-cli upload --file ./image.jpg
Upload media, returns media_id
npx postbridge-cli post --caption "..." --accounts 1,2,3 --media mid_xxx
Post with uploaded media
npx postbridge-cli posts
List recent posts (filters: --status, --platform, --limit, --offset)
Post Bridge has a native MCP (Model Context Protocol) server. If you're using Claude Desktop, ChatGPT, Cursor, or any MCP-compatible client, you can connect directly without this skill.
List all connected accounts with IDs, platforms, usernames, and needs_reconnect (true = repeated dead-token failures paused posting to that account; skip it and tell the user to reconnect in the dashboard, which clears the pause automatically)
create_post
Create/schedule a post. Accepts caption, accounts, media_urls, schedule, use_queue (true or {timezone}), platform configs
list_posts
List posts with filters (platform, status, limit, offset)
get_post
Get full post details by ID
update_post
Update caption, schedule, accounts, or media on a scheduled/draft post
delete_post
Delete a scheduled or draft post
list_analytics
Get analytics (views, likes, comments, shares) with platform/timeframe filters
sync_analytics
Trigger a background refresh of analytics data. Optional platform param to sync a specific platform (tiktok/youtube/instagram)
list_post_results
Check per-platform posting results (success/failure with error details)
list_media
List uploaded media files with IDs and URLs
delete_media
Delete an uploaded media file
MCP tools accept media_urls (public URLs) — the server downloads and uploads them automatically. No need to manually upload media when using MCP.
Platform Configurations
Optional per-platform overrides, passed inside the platform_configurations object on post creation/update, or via --platform-config '<json>' with the CLI. This is the #1 place to get wrong, so read carefully:
Rules
Key by platform name. Every override lives under a platform key: pinterest, instagram, tiktok, twitter, youtube, facebook, linkedin, bluesky, threads, google_business. A field placed at the wrong level (or under the wrong platform) is silently ignored.
Only include platforms you're actually posting to. Don't add a tiktok block if no TikTok account is in social_accounts.
Only include fields you want to override. Everything you omit falls back to the top-level caption / media. caption and media are accepted under every platform key; the other fields are platform-specific and listed below.
Match the accepted values exactly. Enums (placement, trial_graduation, cta_action_type, location, …) only accept the values shown — anything else errors or is dropped.
Every platform accepts:
caption (string) — caption override for that platform only
media (array of media IDs) — media override for that platform only
Platform-specific fields:
Platform (key)
Field
Type / accepted values
What it does
Pinterest (pinterest)
board_ids
array of string IDs
Boards to pin to (IDs, not names). Omit → account default board.
link
string (full URL)
Destination URL the pin links to.
title
string (≤100 chars)
Pin title shown above the caption.
video_cover_timestamp_ms
number (ms)
Video cover frame, e.g. 3000 = 3s in.
Instagram (instagram)
placement
"story"
Publish as a Story (one image/video, no caption/carousel/cover/trial). Omit → Reel/feed.
video_cover_timestamp_ms
number (ms)
Cover frame for a reel/video. Ignored if cover_image is set.
cover_image
string (media ID)
Uploaded image used as the reel cover. Upload first, pass its ID.
is_trial_reel
boolean
Trial reel (non-followers first). Needs Pro/Creator account, 1,000+ followers, public profile. Max 5/day. Not with placement:"story".
trial_graduation
"MANUAL" | "SS_PERFORMANCE"
Trial reel graduation. MANUAL (default) = you decide; SS_PERFORMANCE = auto-graduate on performance in 72h.
user_tags
array of usernames
People-tag accounts (they get notified). @ optional. Feed/carousel/reels only; ignored for stories. Max 20.
collaborators
array of usernames
Invite co-authors: the post also appears on their profile and shares its likes/comments. @ optional. Max 3, public accounts only — a private or wrong handle fails the post. Feed/carousel/reels only; ignored for stories. Publishes immediately; shows on their profile once they accept.
first_comment
string (≤2200)
Comment posted right after the post publishes — good spot for a link or hashtags. Ignored for stories. A failed comment won't fail the post.
TikTok (tiktok)
title
string
Overrides the post title.
video_cover_timestamp_ms
number (ms)
Cover frame, e.g. 3000 = 3s in.
draft
boolean
Send as a native TikTok draft (finish/publish manually in the app, e.g. to add a trending sound). Different from top-level is_draft (which only saves in Post Bridge).
is_aigc
boolean
Label as AI-generated content.
privacy_status
"public" | "private"
private publishes visible only to you. Defaults to public.
auto_add_music
boolean
Photo posts only — ignored on videos. TikTok picks a soundtrack for the carousel. Defaults to true; set false to publish silent.
allow_comment
boolean
Allow comments. Defaults to true.
allow_duet
boolean
Allow Duets. Defaults to true. Video posts only.
allow_stitch
boolean
Allow Stitches. Defaults to true. Video posts only.
disclose_branded_content
boolean
Disclose as paid partnership / branded content. Defaults to false.
disclose_your_brand
boolean
Disclose as promoting your own brand. Defaults to false.
Twitter/X (twitter)
first_comment
string (≤280, 2200 premium)
Reply posted right after the tweet. Put links here — the main tweet strips URLs to dodge X's surcharge. A failed reply won't fail the post.
YouTube (youtube)
title
string (≤100 chars)
Video title override.
contains_synthetic_media
boolean
Disclose realistic altered/AI content ("Altered or synthetic content" label).
thumbnail
string (media ID)
Custom thumbnail. Long-form videos only — ignored on Shorts. Channel must be verified; JPEG/PNG, 1280×720, <2MB.
Facebook (facebook)
placement
"story"
Publish as a Page Story (one image/video, no caption/carousel). Omit → feed post.
first_comment
string (≤2200)
Comment posted right after the post publishes — good spot for a link/CTA. Ignored for stories. A failed comment won't fail the post.
LinkedIn (linkedin)
document_title
string
Title for a PDF (document/carousel) post. Only applies when media is a PDF. Defaults to file name.
Bluesky (bluesky)
—
—
Only caption / media overrides.
Threads (threads)
location
"timeline" | "reels"
Where it appears. timeline (default) or reels (video only).
first_comment
string (≤500)
Reply posted right after the thread publishes — good spot for a link. A failed reply won't fail the post.
Google Business (google_business)
media
array (single image)
One image only — extra images are dropped for GMB (other platforms keep all). No video.
cta_action_type
BOOK | ORDER | SHOP | LEARN_MORE | SIGN_UP | CALL
CTA button. Pair with cta_url (except CALL, which uses the location phone number).
cta_url
string (full URL)
CTA destination. Required when cta_action_type is set (except CALL).
language_code
string (BCP-47)
e.g. "en-US", "es", "fr-CA". Defaults to "en-US".
Example — correct multi-platform config (CLI)
Posting one piece of content to TikTok + Instagram + X + Google Business, with per-platform tweaks:
text
npx postbridge-cli post --caption "New drop is live 🎉" --accounts 44029,44030,44031,44032 \
--platform-config '{
"tiktok": { "draft": true, "is_aigc": false },
"instagram": { "caption": "New drop is live 🎉 tap the link in bio", "video_cover_timestamp_ms": 2000 },
"twitter": { "first_comment": "Grab it here: https://example.com/drop" },
"google_business": { "cta_action_type": "SHOP", "cta_url": "https://example.com/drop" }
}'
Note how the X link lives in twitter.first_comment (not the caption), TikTok uses a native draft, and only the four platforms being posted to appear as keys.
Platform Gotchas (important for agents)
These behaviors are easy to miss and cause silent or confusing failures. Account for them before posting.
Some platforms require media; others accept text-only. These fail a post with no media: youtube (exactly 1 video), tiktok (1 video, or one+ images for a photo post), instagram (1–10 images/videos; a story is exactly 1; PDFs are dropped), pinterest (1 image or video). These accept text-only: twitter/X (up to 4 images, or 1 video), facebook, linkedin (up to 20 images, or 1 video, or 1 PDF document), threads (up to 20 images/videos), bluesky (up to 4 images, or 1 video), google_business (text or a single image; no video). A post can be created with no media and have media added later via posts:update, but it won't publish to a media-required platform until media exists. When a post targets several platforms, each takes what it supports and skips what it can't (e.g. a video serves YouTube; X uses it too).
X (Twitter) strips URLs from captions. Links (http://, https://, www.) are removed from the X caption before posting. This is intentional (link posts on X cost ~13× more per post). If a link is essential for X, put it in twitter.first_comment (links ARE allowed there — it's posted as a reply right after the tweet), not the caption — and tell the user the link won't appear in the X post itself.
Media must be uploaded, not pasted as a raw link. Do not put a Google Drive / Dropbox / arbitrary external URL into media. The media field takes Post Bridge media_ids only. Either upload the file first (CLI/API) or use media_urls (CLI --media-urls, or the MCP media_urls field) with a direct, public file URL that the server can download. A non-direct share link will fail with a generic error and no per-platform results.
Very large videos (~300MB+) can silently drop YouTube, LinkedIn, and X. Those three platforms buffer the whole file server-side and may time out / OOM on huge uploads, producing no result row for them while Instagram/TikTok/Facebook/Threads succeed. If results shows fewer platforms than you posted to, suspect file size — re-encode smaller or shorter. Keep videos reasonably sized.
Each platform posts independently. One platform failing does not stop the others. Always check results --post-id <id> after a publish to confirm per-platform success and read any error details.
TikTok / Instagram caption + sound limits differ. Keep captions concise; for trending-sound workflows use TikTok draft: true so the user can add the sound and publish manually.
What actually fails, measured across 302,000 posts from 7,158 accounts in the
30 days to 2026-08-31. Each platform fails in one dominant way, and the right
response differs:
TikTok: 75% of failures are spam restrictions. The platform's decision
about that account, caused by posting too often. Clears itself in 24 to 48
hours. Reconnecting does nothing. If waiting does not clear it, the user
should post that account manually from the phone for a few days.
YouTube: 84% are the daily upload quota, which is per channel and lower
for new channels. Spread uploads across channels and days.
X: 92% are a 403 spam block, from posting too fast, too repetitively, or
with links.
Instagram: 50% dead token, 41% transient Meta 500s. The 500s often
publish anyway despite reporting failure, so check before republishing or you
will double-post.
Threads and LinkedIn: almost entirely dead tokens. Reconnect.
Pinterest: 46% no valid media attached.
Bluesky: rate limits, takedowns, and unconfirmed emails, which silently
block video upload.
Expected success rates, so an account is judged against its own platform rather
than against 100%: LinkedIn 97%, X 88%, YouTube 88%, Instagram 87%, Facebook
84%, TikTok 82%, Threads 81%, Pinterest 76%, Bluesky 71%.
The distinction that matters: a platform restriction cannot be fixed by
anyone and clears on its own, while a dead token or missing media is actionable.
Telling the user to reconnect when the account is merely restricted wastes days.
Recommended Workflow for Video Content
Optional. Steps 2, 5 and 6 touch the user's machine, so confirm each with them
before doing it rather than assuming consent.
Store videos in a local folder
(runs a local command) Extract a frame with ffmpeg to read any text
overlays. Tell the user you are about to run this and on which file:
text
Skip it if ffmpeg is unavailable or the user would rather describe the video.
Write caption based on video content + hashtags
Upload, create post, then schedule or post instantly
(modifies local files) Optionally move posted videos to a posted/
subfolder to avoid duplicates. Name the exact source and destination paths
and get agreement first. Never delete anything.
(creates a background job) Optionally set a cron to check post status 5
minutes after the scheduled time. Show the user the exact crontab line and
how to remove it before adding it. Do not add one unprompted.
Track performance by checking post results or analytics
Automation Guidelines
When automating posts, follow these rules to keep accounts in good standing:
No duplicate content across multiple accounts on the same platform
No unsolicited automated replies — only post original content or when explicitly requested
No trending manipulation — don't mass-post about trending topics across accounts
No fake engagement — don't automate likes, follows, or comments
Respect rate limits — the API has rate limits, don't spam requests
Use draft mode for review — when in doubt, use is_draft: true or TikTok's draft: true so the user can review before publishing
Publishing confirmation: Unless the user explicitly asks to "post now" or "publish immediately", always confirm before posting. Creating a draft is safe; posting is irreversible and goes live instantly.
Platform Names
Use these exact names for platform filtering and configurations:
instagram — Instagram (Reels, Stories, Feed)
tiktok — TikTok
youtube — YouTube (Shorts)
twitter — X (formerly Twitter)
linkedin — LinkedIn
facebook — Facebook
pinterest — Pinterest
threads — Threads
bluesky — Bluesky
Tips
Post to multiple platforms simultaneously by including multiple account IDs
Stagger posts throughout the day (e.g. 9am + 3pm) for better reach
Use scheduled_at to pre-schedule batches — Post Bridge handles the timing
Use use_queue: true to auto-schedule posts to the user's next available queue slot using their saved timezone — no need to pick a time manually
TikTok draft mode lets you add trending sounds manually before publishing
Keep hashtags to 4-5 per post for best engagement
Check results after posting to see per-platform success/failure
Use analytics:sync to refresh data before checking analytics
Monitor what works and iterate on captions/formats
Use --draft flag when testing to avoid accidental publishing
Character limits vary by platform — keep captions concise for X (280 chars)