Socialync

Publish a pending draft NOW (or, for scheduled drafts, move it into the scheduled queue). Call this AFTER the user has explicitly confirmed in chat that they want to publish the draft. Do NOT call without explicit user consent. If the user has switched on the publish confirmation dialog in Socialync settings (off by default) and their client supports MCP elicitation, Socialync also shows the user a confirmation dialog with the draft: a decline marks the draft rejected and comes back as success false with consent "declined" (never retry; ask the user); no answer within 40 seconds counts as the chat confirmation. The draft must have been created via create_post_draft, schedule_post_draft or create_x_article_draft, must still be pending, must belong to this user, and must not be expired. Returns per-platform success/failure for immediate publishes, or scheduled post IDs for scheduled publishes. A scheduled draft whose time has already passed cannot be approved as is: confirm a new time with the user and pass it as scheduledFor.

Check the user's remaining post quota, subscription plan, and daily per-platform posting limits. Always call this before posting.

Get presigned upload URLs for media you generated locally (e.g. rendered carousel slides or a video) that is too large to inline as base64Images. Returns one uploadUrl per file -- HTTP PUT each file's raw bytes to its uploadUrl with the matching "Content-Type" header (no auth header), then call finalize_media_upload with the returned uploadId. A batch is EITHER up to 10 images (one carousel, kept in order) OR exactly one video. Images: jpeg/png/webp/gif, max 25MB each. Video: max 512MB. Upload URLs expire in 1 hour. This is for media YOU produced; if the USER uploaded media in the Socialync app, use list_media instead. If the PUT can't connect (a sandbox network block, a proxy 403, "host not allowed", a DNS failure), do not retry it and do not call finalize_media_upload. Tell the user plainly that their AI app can't reach Socialync's upload server, then offer the two ways forward: (1) they add the file in Socialync (socialync.io: start a post and add the file, no need to finish it), come back, and you find it with list_media; or (2) they allow the upload host in their AI app's code or network settings and you try again. Images up to 8MB each can also go inline as base64Images instead.

Hold a post as a pending draft WITHOUT sending it. Nothing reaches any platform until you show the user the exact post, they say yes in chat, and you call approve_draft(draftId); a draft nobody approves expires after 24 hours and the post never goes out. Never tell the user to open the Socialync app to approve it: the whole flow stays in this chat. When the user has already confirmed the post, call publish_now instead (one step). Returns a draft_id, expiry, and dailyDraftsRemaining. Supports up to 10 images total via imageUrls (public https URLs) and/or base64Images (image bytes). Cannot attach video. Cannot draft to TikTok or YouTube (use schedule_post_draft for those). Instagram requires at least one image. Hard cap: 10 drafts per UTC day per profile -- platform-security mechanism to keep the user's accounts under Meta/X/LinkedIn spam-detection thresholds, not a Socialync restriction. ALWAYS run validate_post with these same arguments FIRST and resolve every error it reports before calling this.

Hold a native X ARTICLE -- the long-form rich-text format with a headline, NOT a regular post -- as a pending draft WITHOUT publishing it. Pass scheduledFor to publish it later instead of right away. Show the user the headline, full body, images and time, and when they say yes in chat call approve_draft(draftId); never tell the user to open the Socialync app to approve it. Use publish_x_article_now instead when the user has already confirmed in chat and wants it out now. The user's connected X account must have an X Premium subscription (any tier) -- without it X refuses with a 403 at publish time. Supported markdown: # ## ### headings, bold, italic, - bullet and 1. numbered lists, > blockquotes, links. Images: a cover via coverImageUrl, or via coverMediaId for an image uploaded with create_media_upload and finalize_media_upload, and an image inside the body on its own line as (JPG, PNG or WEBP, up to 20 images including the cover; Socialync copies them into its own storage when the draft is made). Tables and code blocks degrade to plain text. To publish later, pass scheduledFor to create_x_article_draft and approve it; Socialync publishes it at that time. Articles count toward the same 10/day cap as posts.

Cancel a pending scheduled post before it publishes. Pass a postId to cancel a single platform entry, or a groupId to cancel every platform in a grouped multi-platform post at once (the ids publish_scheduled returns together share a groupId). Destructive and not undoable -- show the user what will be cancelled and get explicit confirmation in chat first. If the user has switched on the publish confirmation dialog in Socialync settings (off by default) and their client supports MCP elicitation, Socialync also asks the user to confirm the cancellation in a dialog; a decline cancels nothing and comes back as success false with consent "declined"; no answer within 40 seconds counts as the chat confirmation. Already-published posts cannot be cancelled. Call get_scheduled_posts to find ids.

Finalize a presigned upload started with create_media_upload, after you have PUT every file to its uploadUrl. Verifies the bytes landed, checks size/type, and returns a mediaId (e.g. "upload:abc123") usable in schedule_post_draft or publish_scheduled. For an image batch the single mediaId carries the whole carousel in upload order. The media is durable (hosted on Socialync's bucket), so you can schedule the post for any future publish date.

Use Socialync's AI to generate platform-optimized captions. The AI knows each platform's tone, character limits, and best practices. Requires a paid plan; not available on the free plan.

Get analytics for a week, a month, or any number of days up to 365, the same numbers as the Socialync analytics page. Views, likes, comments, shares and saves count only what was gained during the window, so a quiet week can read 0 comments even when older posts have comments. For each post's lifetime totals, use get_top_posts or get_post_insights. Also returns the current follower count and its net change, plus percentage changes against the previous window of the same length. Saves come only from platforms whose API reports them (Instagram); the others show saves as "not available". YouTube is left out of cross-platform totals and has no comparisons, because YouTube's API policy does not allow metrics derived from its data. Set breakdown="by_platform" to get separate numbers for each connected platform, YouTube included. Set includeTimeseries=true to also get daily snapshots per platform, including each day's follower count.

Find the days and times the user's own posts got the most engagement, per platform, from their recent history. Returns up to 3 posting windows per platform (e.g. Tue 6 PM to 9 PM) with the number of posts behind each and their average engagement (likes + comments + shares) and views. A window needs at least 2 posts to count, so accounts with few posts get few or no windows; say so rather than guessing. Times are in the time zone you pass, or the zone the user schedules in. YouTube is not included. Use it to pick a scheduledFor for publish_scheduled or update_scheduled_post.

Read the comments on one of the user's published posts: who said what, when, and the replies under each. Works for Instagram, YouTube, Threads, LinkedIn Company Pages (paid plans) and Bluesky; X, TikTok and Facebook comments are managed in the Socialync app. Use it to see what the audience is asking or reacting to, to spot ideas for the next post, or to find a comment to answer with reply_to_comment. Get post ids from get_top_posts or get_post_history. Shows up to the 60 most recent comments.

Check the status of a draft created via create_post_draft, schedule_post_draft or create_x_article_draft. Returns the current state (pending, approved, rejected, expired, published) so you can tell the user what happened. A pending draft is waiting for approve_draft after the user says yes in chat. Only returns drafts owned by this user.

Get the user's recent post history with per-platform success/failure tracking. Useful for checking what was posted and what failed. Each failed platform includes the raw error and a reason object (code, plain message, action, retryable) that says whether the fix is reconnecting the account, editing the post, or retrying. When the account has no active plan (payment failing or plan ended), the response carries accountHold: posts queued before it stay pending and do not publish until it is resolved, so a "pending" entry past its time means held, not stuck. get_scheduled_posts shows which posts are affected.

Everything about ONE published post: views, likes, comments, shares, and for videos on Instagram, Facebook and YouTube how people watched it: average watch time, share of viewers still watching at 3 seconds (the hook), the retention curve (where viewers stopped watching), the biggest drop, replays, follows gained, YouTube traffic sources and YouTube's comparison with similar videos. Also returns the same post on every other platform it was published to, side by side, and how it compares with the user's median post on that platform. Use it to explain why a post worked or fell short and what to change in the next edit (e.g. "viewers left at 0:04, right after the intro"). Get post ids from get_top_posts or get_post_history. In clients that support interactive apps this renders as a chart the user can click to jump the video. Retention positions are in seconds when the video length is known.

List the user's scheduled posts: pending ones, failures from the last 14 days and posts published in the last 2 days (get_post_history has older published posts). Shows platform, profileId, caption, scheduled time and status. caption is the text that platform will publish: its own override from platformSpecificSettings when the post has one (captionIsPlatformOverride is then true), otherwise the shared caption. instagramTrialReel is "MANUAL" or "AUTO" on an Instagram post that will publish as a Trial Reel, and null on every other post. A post with status "failed" carries an error object: code (stable, e.g. connection_signed_out, connection_reauth_required, trial_reel_ineligible, media_rejected, rate_limited, platform_unavailable), a plain message to relay to the user, action (reconnect, edit_post, retry, wait_and_retry), retryable, retryAfterReconnect, and the platform's raw platformError. When action is "reconnect", tell the user which account to reconnect in Socialync Settings; do not reschedule until they have. A post with status "held" did not publish because the account had no active plan (payment failing or plan ended) when it came due, and it will never publish late on its own: its held object has the reason and message, and the fix is to reschedule it. A still-pending post carries onHold when the account currently has no active plan: it publishes only if the payment goes through within an hour of its time, so tell the user to update their payment in Socialync Billing.

Get the user's posts with engagement metrics, ranked by engagement or recency. Returns the same data as the Top Performing Posts and Recent Posts tables on the analytics page: views, likes, comments, shares, engagement rate, and a status that compares each post with this account's own usual on that platform (good = at least twice its usual, average = around its usual, below_usual = under half of it, viral = huge reach on any account). not_rated means there are fewer than 5 settled posts to compare with, the post is under 2 days old, or it is a YouTube post, which carries no status, rate or engagement total because YouTube's API policy does not allow metrics derived from its data. no_data means nothing has been collected for that post yet. Video posts on Instagram, Facebook and YouTube also carry a "watch" block with how people watched (average watch time in seconds, share held past the 3 second mark, skip rate, replays, follows gained); includeRetention=true adds the retention curve (t = position in the video 0..1, v = share of plays still watching) and YouTube traffic sources.

Import a video made with Claude Motion into the user's Socialync media library so it can be posted. Use this when the user wants to post, schedule or send a Claude Motion video to Socialync. Call it promptly with the download URL Claude Motion provides (it expires within minutes). Returns a mediaId to pass to publish_scheduled or schedule_post_draft (video posts work on every platform, YouTube also needs a title). Importing does not publish anything. Schedule the video within 12 hours of importing: media that no post uses is cleaned up after that.

List the user's saved audiences. An audience is a named group of connected accounts the user built in Socialync (e.g. "Core 12"), reusable as a posting target. Returns each audience with id, name, scope, member count, and the members (platform + account label). Pass an audience id as the audienceId param on create_post_draft / schedule_post_draft / publish_now / publish_scheduled to post to that group instead of listing platforms; anything the audience cannot reach on the chosen profile is reported back in skippedMembers.

List all connected social media platform accounts for a profile. Returns platform name, profile name, and connection status for each. A connection with requiresReconnect true cannot publish: its reason says why in plain words, and scheduled posts to it will fail until the user reconnects it in Socialync Settings. X connections also carry maxCaptionLength (280 free, 4000 with X Premium) and xPremium. Pass profileId to inspect a specific authorized profile; omit it to use the single/default authorized profile.

List media (videos/images) the user already has in Socialync, available to schedule via the mediaId parameter of schedule_post_draft / publish_scheduled. Sources: uploads from the last 24 hours, active drafts, and pending scheduled posts. Use this when the user wants to post "the video I just uploaded" or attached a video file in chat (you cannot receive video files -- send them to socialync.io to upload it, then find it here). IMPORTANT: items marked unattached expire about 12 hours after upload unless scheduled -- schedule them promptly.

List the Socialync profiles this connection can manage. Returns each authorized profile with id, name, whether it is the default, and its connected-platform count. Call this first when posting and pass the chosen profile id as the profileId param on publish_now / publish_scheduled / create_post_draft / schedule_post_draft. Every profile can be managed by AI regardless of plan; what bounds a free-plan profile is its monthly post allowance, applied when posts publish.

Publish a post IMMEDIATELY to one or more platforms. PREFERRED tool when the user is interacting with you in chat -- it skips the Socialync drafts page entirely. If the user has switched on the publish confirmation dialog in Socialync settings (off by default) and their client supports MCP elicitation, Socialync shows the user a confirmation dialog with the exact post before publishing: a decline rejects it and comes back as success false with consent "declined" (never retry; ask the user), and no answer within 40 seconds counts as the confirmation the user already gave you in chat. On other clients there is NO dialog and this publishes as soon as you call it. Either way, before calling you MUST show the user the exact caption, platforms, and images you will post, and get their explicit confirmation in the chat. Treat this the same way you would treat sending an email on someone's behalf. If the user uploaded image(s) to you in the conversation, pass them via base64Images (preferred) -- Socialync will host them for you. If the user gave you a public image URL, pass it via imageUrls. Returns per-platform success/failure. Same validation as create_post_draft: text and/or up to 10 images total (URLs + base64 combined), Instagram requires at least one image, no TikTok/YouTube (use publish_scheduled for those), 10/day cap per profile (platform-security mechanism to keep accounts under spam-detection thresholds). ALWAYS run validate_post with these same arguments FIRST and resolve every error it reports before calling this.

Schedule a post for future publishing. PREFERRED tool when the user is interacting with you in chat -- skips the Socialync drafts page. If the user has switched on the publish confirmation dialog in Socialync settings (off by default) and their client supports MCP elicitation, Socialync shows the user a confirmation dialog with the exact post and time before it enters the queue: a decline rejects it and comes back as success false with consent "declined" (never retry; ask the user), and no answer within 40 seconds counts as the confirmation the user already gave you in chat. On other clients there is NO dialog: once you call this, the post enters the scheduled queue and will publish automatically at scheduledFor. Either way, before calling, show the user the caption, platforms, media, and the scheduled time, and get their explicit confirmation in chat. Media options: base64Images (user uploaded images to you in chat), imageUrls (public https), videoUrl (ONE public https video URL -- Socialync copies it into its own storage at call time), or mediaId (media already in Socialync, from list_media -- use for "the video I uploaded"). YouTube allowed for VIDEO posts only (and needs title). TikTok takes one video or a photo post of images (a swipeable photo carousel). Returns scheduled post IDs. Same validation as schedule_post_draft. 10/day cap per profile per publish day (UTC date of scheduledFor). ALWAYS run validate_post with these same arguments FIRST and resolve every error it reports before calling this.

Publish a native X ARTICLE immediately -- the long-form rich-text format with a headline, NOT a regular post. If the user has switched on the publish confirmation dialog in Socialync settings (off by default) and their client supports MCP elicitation, Socialync shows the user a confirmation dialog with the headline and body before publishing (a decline comes back as success false with consent "declined"; never retry it; no answer within 40 seconds counts as the chat confirmation). On other clients there is NO dialog. Either way, before calling, show the user the exact headline and full body and get their explicit confirmation in chat, the same way you would before sending an email on their behalf. Returns the article id and the URL of the seed post that announces it. The user's connected X account must have an X Premium subscription (any tier) -- without it X refuses with a 403 at publish time. Supported markdown: # ## ### headings, bold, italic, - bullet and 1. numbered lists, > blockquotes, links. Images: a cover via coverImageUrl, or via coverMediaId for an image uploaded with create_media_upload and finalize_media_upload, and an image inside the body on its own line as (JPG, PNG or WEBP, up to 20 images including the cover; Socialync copies them into its own storage when the draft is made). Tables and code blocks degrade to plain text. To publish later, pass scheduledFor to create_x_article_draft and approve it; Socialync publishes it at that time. Articles count toward the same 10/day cap as posts.

Reply to one comment on one of the user's published posts, as the user's own account, on Instagram, Threads, LinkedIn Company Pages (paid plans) or Bluesky. The reply is public and goes out immediately. Before calling, show the user the comment and the exact reply and get their explicit confirmation in chat, one reply at a time; never reply in bulk or without the user seeing each one. If the user has switched on the publish confirmation dialog in Socialync settings and their client supports MCP elicitation, Socialync also shows a dialog; a decline sends nothing and comes back as success false with consent "declined". YouTube and X replies are sent by the user in the Socialync app. Get the commentId from get_comments. Limit: 30 replies per day.

Hold a post to be SCHEDULED for future publishing as a pending draft WITHOUT scheduling it. Nothing enters the schedule until you show the user the exact post and time, they say yes in chat, and you call approve_draft(draftId); a draft nobody approves expires after 24 hours. Never tell the user to open the Socialync app to approve it: the whole flow stays in this chat. When the user has already confirmed the post, call publish_scheduled instead (one step). Once approved, it enters the scheduled queue and publishes automatically at scheduledFor. Returns a draft_id, expiry, and dailyDraftsRemaining for the target publish day. Media: up to 10 images via imageUrls/base64Images, OR one video via videoUrl, OR existing Socialync media via mediaId (from list_media). YouTube is allowed ONLY for video posts (and needs title). TikTok takes one video or a photo post of images (a swipeable photo carousel). Instagram requires media. Hard cap: 10 drafts per UTC day per profile (the day determined by scheduledFor). Each future day has its own independent 10-cap. ALWAYS run validate_post with these same arguments FIRST and resolve every error it reports before calling this.

Change a scheduled post that has not published yet: its time, its caption (for every platform, or per platform), the YouTube title, the first comment, or drop platforms from it. Pass a groupId to change every platform of a grouped post together (the ids publish_scheduled returns share a groupId), or a postId for one platform's entry. Prefer this over delete_scheduled_post plus a new post: it keeps the post's id, media and settings. Media cannot be swapped and platforms cannot be added here; for that, cancel and schedule again. Before calling, show the user exactly what will change and get their explicit confirmation in chat. If the user has switched on the publish confirmation dialog in Socialync settings (off by default) and their client supports MCP elicitation, Socialync also shows a dialog; a decline changes nothing and comes back as success false with consent "declined". A new time must be at least 3 minutes away and inside the plan's scheduling window; moving a post to another UTC day uses that day's 10-post allowance. Posts already publishing, published, failed or cancelled are skipped with a reason. Call get_scheduled_posts to find ids.

Validate a post BEFORE creating or publishing it. Checks caption length, link count, media type/count/size, image aspect ratio, video duration, and connection/token health for every target platform -- without creating anything. ALWAYS call this with the exact arguments you intend to pass to create_post_draft / schedule_post_draft / publish_now / publish_scheduled, BEFORE calling them, and again after any edit. Errors are guaranteed publish failures: fix them or drop that platform. Warnings publish but degraded (truncated caption, blur-fitted image, heuristic link count) -- surface them to the user before publishing. Pass scheduledFor to validate under the scheduled rules (all 8 platforms, video allowed); omit it for immediate-post rules. Does not check the daily quota (call check_quota). base64Images cannot be pre-validated -- they are checked at draft time once Socialync hosts them.