Validate a post (dry run)
validate_postRead-onlyIdempotent
Checks a post against every account's network rules without saving anything and returns ALL issues at once. It approves nothing by itself: read next_step, which says in plain words what to do (fix issues, ask the human to confirm and pass confirmation_token, or create_post) (caption length, format support, media requirements, video length and shape, YouTube title, TikTok privacy and commercial fields, disconnected accounts). With schedule_at it also reports the X link allowance, the key's caps and whether the send would need confirmation_token from the returned plan, plus the dispatch plan. Run it before create_post when in doubt; it needs only the read scope and works in a sandbox.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| poll | No | A poll on X, LinkedIn and Mastodon. A poll post carries no media. | |
| label | No | Internal name for the post (never published). | |
| format | No | Format for every account. Default per network: Facebook/Instagram FEED (REEL with a video), YouTube SHORT, TikTok VIDEO, LinkedIn FEED (VIDEO with a video), X FEED. Unsupported on a network = an issue, not a silent change. | |
| caption | Yes | Master text. Goes to every account unless per_channel overrides it. X: 280 characters; Bluesky: 300; Mastodon: 500 (links count as 23); Instagram and TikTok: 2,200; Telegram: 4,096 for text, 1,024 under photos, a video or a file. | |
| cta_url | No | Link to track. Each account gets its own short link with UTM tags, placed in the caption or the first comment per network. Never added on X (paid links). | |
| gbp_end | No | Google Business Profile event or offer: when it ends (not before gbp_start), same format. | |
| post_id | No | Existing draft or approved post; enables checking its approval state and preserving its tracked URLs. | |
| campaign | No | utm_campaign value for the tracked links. | |
| cta_text | No | ||
| draft_id | No | Reserved post ID returned by validate_post or needs_confirmation. Pass it unchanged to create_post so previewed tracked URLs and the confirmation plan remain exact. | |
| gbp_link | No | Google Business Profile: where the button (or an offer's "redeem online") leads, https. Omitted: cta_url. Either way it becomes a tracked short link; links in the post's text aren't clickable on Google. | |
| gbp_type | No | Google Business Profile: STANDARD (an update, the default), EVENT or OFFER. Events and offers need gbp_title, gbp_start and gbp_end. | |
| x_thread | No | X: up to 5 follow-up posts that continue the post as a thread (each is a paid X post). | |
| alt_texts | No | Image descriptions for screen readers, by media id (images in media_ids). Sent to Instagram, Facebook, X, LinkedIn, Bluesky and Mastodon. Stored on the image, so later posts reuse it; an empty string clears it. | |
| gbp_start | No | Google Business Profile event or offer: when it starts, in the location's own time, "2026-11-05" (the whole day) or "2026-11-05T18:30". No time zone. | |
| gbp_terms | No | Google Business Profile offer: terms and conditions (optional). | |
| gbp_title | No | Google Business Profile event or offer: its title (required there, up to 58 characters). | |
| group_ids | No | Account groups — every active account in them is added to channel_ids. | |
| media_ids | No | Media from upload_media_from_url, in display order. Instagram, TikTok and YouTube need media; Reels/Shorts/Video need a video file. | |
| gbp_button | No | Google Business Profile update or event: the button. CALL dials the profile's phone number (no link); the others lead to gbp_link or cta_url. Omitted with a link: LEARN_MORE. Offers get Google's own button instead. | |
| gbp_coupon | No | Google Business Profile offer: a coupon code (optional). | |
| channel_ids | No | Accounts to publish to (ids from list_channels). | |
| per_channel | No | Per-account overrides and network fields. TikTok accounts need tiktok_privacy here. | |
| schedule_at | No | Optional: also check allowances, caps and confirmation for this time. | |
| video_title | No | Video title on Facebook and LinkedIn videos (YouTube uses youtube_title). | |
| ai_generated | No | Made or meaningfully altered with AI. Sent as each network's AI label: Instagram, Facebook Reels, YouTube (altered or synthetic content), TikTok (AI-generated), X (made with AI), Pinterest (AI-modified disclosure). | |
| workspace_id | Yes | Workspace id from list_workspaces | |
| youtube_tags | No | YouTube tags, 500 characters in total. | |
| first_comment | No | Posted right after the post as its first comment (the usual place for a lead link). Facebook, Instagram, YouTube: a comment. X: a reply (a link in it counts against the X link allowance). LinkedIn company Pages: a comment as the Page. LinkedIn profiles and TikTok: skipped (list_channels first_comment=false). | |
| post_language | No | Mastodon: the post's language as an ISO 639-1 code (he, en, es…); omitted = the account's default. | |
| threads_topic | No | Threads: the post's topic, 1–50 characters, no period or ampersand (e.g. Recipes). | |
| youtube_title | No | YouTube video title (default: first line of the caption). Overridable per channel. | |
| cover_media_id | No | Cover image for the post's video: an IMAGE id from upload_media_from_url (not in media_ids). A cover the network refuses never fails the post: the result carries a notice. null removes it. Per network ("Cover at the start of the video" is cover_first_frame): Facebook: The image becomes the thumbnail of the video or Reel. Stories have no cover. Instagram: The image becomes the Reel's cover, in the feed and on the profile. Stories have no cover. YouTube: The image becomes the video's thumbnail. YouTube allows this only for phone-verified channels (youtube.com/verify); without that, the video goes up with a thumbnail YouTube picks. X: X has no cover setting: it shows the video's first frame. To show your cover, turn on "Cover at the start of the video". LinkedIn: The image becomes the video's thumbnail. TikTok: TikTok takes no cover image through its API, only a moment of the video, and applies even that only to public posts (a private post shows the first frame). To always show your cover, private posts included, turn on "Cover at the start of the video". Bluesky: Bluesky has no cover setting: it shows the video's first frame. To show your cover, turn on "Cover at the start of the video". Telegram: The image becomes the video's cover in the channel. Mastodon: The image is shown on the video on Mastodon until it's played. Threads: Threads has no cover setting: it shows the video's first frame. To show your cover, turn on "Cover at the start of the video". Pinterest: The image becomes the video Pin's cover on Pinterest. Google Business Profile: Google Business Profile posts take no video, so there is no cover. | |
| paid_promotion | No | Paid promotion or partnership disclosure: YouTube (paid product placement), X (paid partnership). TikTok uses tiktok_commercial. | |
| pinterest_link | No | Pinterest: where the Pin leads (https). Omitted: cta_url. Either way it becomes a tracked short link; links in the description aren't clickable on Pinterest. | |
| content_warning | No | Mastodon: a content warning shown before the post (readers tap to see it; it also hides images). Counts toward the 500 characters. | |
| pinterest_title | No | Pinterest: the Pin's title, up to 100 characters (feeds show about the first 40). The caption is the Pin's description (≤800). | |
| stagger_seconds | No | Deprecated: [min, max] — use stagger_min_seconds and stagger_max_seconds. | |
| telegram_silent | No | Telegram: send without a sound, so channel subscribers get no notification. | |
| tiktok_cover_ms | No | TikTok: which frame of the video becomes the cover, in milliseconds from the start (TikTok can't take a cover image). TikTok applies it to public posts only; private posts show the first frame. To show your cover image on every TikTok post, public or private, use cover_media_id with cover_first_frame instead. Default: the first frame. | |
| youtube_license | No | YouTube license (default youtube). | |
| youtube_privacy | No | YouTube: public (default), unlisted or private. | |
| x_reply_settings | No | X: who can reply (default everyone): following, mentionedUsers, subscribers or verified. | |
| cover_first_frame | No | Put the cover image (cover_media_id) at the start of the video, as its first two frames (~1/15 s), so networks that show the video's first frame show your cover: true = only where the network can't take a cover image (TikTok, X, Bluesky, Stories), "all" = on every network, false = never. The original video isn't changed; Shager publishes a copy. Default when omitted: true if the post has a cover and goes to TikTok, X or Bluesky, else false. | |
| threads_link_card | No | Threads text post (no media): an https link shown as a card under the text (link_attachment). Without it, Threads previews the first link in the text. | |
| pinterest_board_id | No | REQUIRED for a Pinterest account (per_channel, since each account has its own boards): the board the Pin goes to, one of that account's pinterest.boards from list_channels. | |
| youtube_embeddable | No | YouTube: allow embedding on other sites (default true). | |
| facebook_pin_to_top | No | Facebook: pin the post to the top of the Page (feed posts). | |
| instagram_user_tags | No | Instagram single photo: people tagged on it, x/y from 0 to 1 measured from the top-left. | |
| linkedin_visibility | No | LinkedIn: PUBLIC (default), CONNECTIONS or LOGGED_IN. | |
| mastodon_visibility | No | Mastodon: who sees the post: public (default), unlisted (quiet public: not in public timelines or hashtags) or private (followers only). | |
| stagger_max_seconds | No | Longest pause between two accounts of the same network (default 90). | |
| stagger_min_seconds | No | Shortest pause between two accounts of the same network (default 30). Facebook and Instagram share one lane. | |
| youtube_category_id | No | YouTube category id (default 22, People & Blogs). | |
| youtube_playlist_id | No | YouTube: add the video to this playlist of the channel (per_channel, since each channel has its own playlists). | |
| facebook_link_button | No | Facebook text post: a button (e.g. LEARN_MORE, SHOP_NOW, SIGN_UP, BOOK_NOW) that opens the post's link, usually cta_url. If Facebook refuses the button, the post goes without it. | |
| instagram_trial_reel | No | Instagram trial Reel, shown to non-followers first: MANUAL (you share it later from the app) or SS_PERFORMANCE (shared automatically if it performs well). | |
| instagram_location_id | No | Instagram: the location shown on the post, as the numeric id of a Facebook Page for that place (Meta's location_id; Shager has no place search yet, so pass an id you already know). Feed photos, carousels and Reels; per_channel to vary it per account. | |
| threads_reply_control | No | Threads: who can reply: everyone (default), accounts_you_follow, mentioned_only or followers_only. | |
| youtube_made_for_kids | No | YouTube's made-for-kids declaration (COPPA). Required explicitly when targeting YouTube; declare whether the video is made for children. | |
| instagram_comments_off | No | Instagram: turn comments off right after publishing. | |
| instagram_collaborators | No | Instagram: up to 3 usernames invited as collaborators (feed, carousel, Reel). The post appears on their profile once they accept in the app. | |
| instagram_share_to_feed | No | Instagram Reel: also show it in the profile's main grid (default true). | |
| linkedin_disable_reshare | No | LinkedIn: stop others from resharing the post. | |
| youtube_notify_subscribers | No | YouTube: notify subscribers about the upload (default true). |