locationIdstringopcional
The location's id (from list_locations). Accepts the database ID or public loc- ID. IDs must belong to the authenticated agency and permitted client.
clientIdstringopcional
Client id (for brand-level posts), from list_clients. Accepts the database ID or public cli- ID. IDs must belong to the authenticated agency and permitted client.
namestringobligatorio
Internal post name/label. Required, non-empty, ≤255 characters.
postType"announcement" | "event" | "offer"obligatorio
Post type. `announcement` is supported by all platforms. `event` and `offer` are GOOGLE-ONLY — if any social platform (facebook, instagram, x, linkedin, pinterest, mastodon, bluesky, youtube) is selected, postType must be `announcement`.
platforms("google" | "facebook" | "instagram" | "x" | "linkedin" | "pinterest" | "mastodon" | "bluesky" | "youtube")[]opcional
Target platforms. Valid values: google, facebook, instagram, x, linkedin, pinterest, mastodon, bluesky, youtube. Required unless you name exact accounts with `connectionIds` instead; unknown values are rejected. e.g. ["google","facebook","instagram"].
connectionIdsstring[]opcional
Optional exact targets: the connection ids to publish to (from list_connected_accounts: a location-bound one, with a clientLocationId, or a brand-level page). When given, the post goes to exactly these and its platforms are theirs; otherwise each platform in `platforms` resolves to the location's connection.
messageGooglestringopcional
Caption for Google. Required when `google` is selected (unless draft). Max 1500 characters.
messageFacebookstringopcional
Shared social caption — used by facebook, instagram, x, linkedin, pinterest, mastodon, bluesky, youtube. Required when any of those is selected (not for a tiktok-only or youtube-only selection, where the caption is optional; Google uses messageGoogle instead) is selected, unless draft. It is validated against EACH selected platform's character limit: facebook 30000, instagram 2200, x 280 WEIGHTED characters rather than typed ones — Japanese/Chinese/Korean characters and emoji cost 2 each and any link costs a flat 23, so a non-Latin caption fits roughly 140 typed characters; setting linkUrl appends that link to the caption for a further 25 weighted (X thread mode is exempt from the limit entirely), linkedin 2000, pinterest 500, mastodon 500, bluesky 300, youtube 5000. The message must fit the smallest limit among the selected social platforms that don't have their own caption in captionOverrides (a platform with an override is checked against its override and its own limit instead).
ctaType"learn_more" | "sign_up" | "order_online" | "book" | "buy" | "call_now"opcional
Call-to-action type. For a Google `offer`, ctaType AND ctaUrl are both required. learn_more/sign_up/order_online/book/buy all require ctaUrl; call_now does not.
ctaUrlstringopcional
Call-to-action URL. Required for a Google offer and for CTA types other than call_now.
mediaUrlsobject[]opcional
Media items, one entry per platform attachment: [{ "url", "platform", "type": "image"|"video" }]. The `platform` on each item must be one of the target platforms and controls which per-platform media rules apply. Per-platform limits (violations are rejected): google = no media constraints enforced here; facebook = ≤10 images OR ≤1 video, no mix (carousel: 2–10 image cards, images only); instagram = requires ≥1 item, ≤10 images OR ≤1 video, images and video cannot be mixed; x = ≤4 images OR ≤1 video, no mix; linkedin = ≤5 images OR ≤1 video, no mix; pinterest = image only (no video), exactly 1 image, required; mastodon = ≤4 images OR ≤1 video, no mix; youtube = video only (no images), exactly 1 video, required; up to YouTube's own 256 GB / 12 h limit.
urlstringopcional
Publicly reachable media URL (http/https).
platform"google" | "facebook" | "instagram" | "x" | "linkedin" | "pinterest" | "mastodon" | "bluesky" | "youtube"opcional
Which target platform this media attaches to.
type"image" | "video"opcional
Media kind.
eventTitlestringopcional
Event/offer title. For a Google event or offer this is required (unless draft) and must be ≤58 characters.
eventStartAtstringopcional
Event/offer start (ISO timestamp). Required for Google event/offer posts (unless draft).
eventEndAtstringopcional
Event/offer end (ISO timestamp). Required for Google event/offer posts (unless draft); must be after the start.
offerTermsstringopcional
Offer terms (offer posts).
offerCouponCodestringopcional
Offer coupon code.
offerRedeemUrlstringopcional
Offer redemption URL.
scheduledForstringopcional
Schedule for this ISO timestamp (must be in the future; omit to publish now).
youtubeTitlestringopcional
YouTube only (ignored otherwise): video title, ≤100 characters, no < or >. Defaults to `name`. The shared social caption (messageFacebook) becomes the video description (≤5000 bytes, no < or >). YouTube is available only on accounts with YouTube enabled; otherwise a YouTube target is rejected.
youtubePrivacyStatus"private" | "unlisted" | "public"opcional
YouTube only: visibility. Defaults to private.
youtubeMadeForKidsbooleanopcional
YouTube only: whether the video is made for kids (COPPA). Required to publish to YouTube.
youtubeCategoryIdstringopcional
YouTube only: numeric video category id, e.g. "22" (People & Blogs, the default).
youtubeTagsstring[]opcional
YouTube only: tags, ≤500 characters in total (commas count; a tag with a space costs 2 more).
youtubeDefaultLanguagestringopcional
YouTube only: BCP-47 language of the title and description.
youtubeAudioLanguagestringopcional
YouTube only: BCP-47 language spoken in the video.
youtubeLocalizationsstringopcional
YouTube only: JSON object keyed by BCP-47 language, each with title and description. Requires youtubeDefaultLanguage.
youtubeRecordingDatestringopcional
YouTube only: ISO timestamp when the video was recorded.
youtubePublishAtstringopcional
YouTube only: future ISO timestamp for native YouTube scheduling. Requires private visibility; must follow the Synup upload time.
youtubePublicStatsViewablebooleanopcional
YouTube only: show extended video statistics publicly.
youtubeNotifySubscribersbooleanopcional
YouTube only: notify channel subscribers of the upload. Defaults to true.
youtubeEmbeddablebooleanopcional
YouTube only: allow embedding on other sites.
youtubeLicense"youtube" | "creativeCommon"opcional
YouTube only: license.
youtubeSyntheticMediabooleanopcional
YouTube only: the video contains realistic altered or synthetic content.
youtubePaidPlacementbooleanopcional
YouTube only: the video contains paid product placement.
youtubeThumbnailUrlstringopcional
YouTube only: custom thumbnail image URL (JPEG/PNG), set after upload. The channel must be phone-verified for YouTube to accept it.
youtubePlaylistIdsstring[]opcional
YouTube only: additional playlist ids; all selected memberships are synchronized after upload or edit.
youtubePlaylistIdstringopcional
YouTube only: id of one of the channel's own playlists; the video is added to it after upload.
youtubeCaptionsobject[]opcional
YouTube only: caption tracks attached after upload, each { url (an .srt/.vtt file), language (e.g. "en"), name }. Each costs 400 YouTube quota units.
urlstringopcional
Caption file URL
languagestringopcional
Language code, e.g. en
namestringopcional
Track name shown to viewers
linkUrlstringopcional
Unified link for the post; each platform places it per its own rules (CTA button, in-caption link, pin link).
linkCtaKeystringopcional
Which call-to-action label the unified link uses (same keys as ctaType).
utmobjectopcional
UTM parameters appended to the unified link.
linkOverrideobjectopcional
Per-platform link overrides, keyed by platform.
linkAppendobjectopcional
Append the link to the caption on these platforms.
ctaUrlFacebookstringopcional
Facebook-only call-to-action URL (overrides ctaUrl on Facebook).
xThreadbooleanopcional
X only: split a long caption into a thread instead of rejecting it.
scheduleLocalTimestringopcional
Wall-clock schedule time (e.g. 2026-10-12T09:00) interpreted per scheduleZoneMode. Requires scheduleZoneMode.
scheduleZoneMode"target_local" | "fixed_zone"opcional
How scheduleLocalTime is interpreted: in each target's local zone, or one fixed zone.
scheduleTimeZonestringopcional
IANA zone, required when scheduleZoneMode is fixed_zone (e.g. America/New_York).
timeZoneMode"target_local" | "fixed_zone"opcional
Alias of scheduleZoneMode kept for the composer.
videoCoverUrlstringopcional
Video cover image URL (platforms that support covers).
videoCaptionsUrlstringopcional
Subtitle file URL (.srt/.vtt) for the video.
videoCaptionsLanguagestringopcional
Language code of the subtitle file, e.g. en.
captionOverridesopcional
Per-platform captions that replace the shared caption (messageFacebook) on that platform only, e.g. { "x": "Short version #sale", "linkedin": "Longer, professional version" }. Supported: facebook, instagram, linkedin, x, bluesky, mastodon, threads, pinterest, tiktok, youtube; other platforms (Google, Reddit, Medium, Substack, Vimeo, Dailymotion) are refused (they publish the shared caption). Each is checked against its own platform's limit. On update, only the platforms you name change; set one to null (or "") to go back to the shared caption, or pass null for the whole field to clear all. Shared messageFacebook stays the default for every platform without an entry.
facebookCaptionstringopcional
Facebook-only caption, used instead of the shared social caption. Prefer captionOverrides.facebook.
facebookCtaTypestringopcional
Facebook-only call-to-action button type.
facebookFirstCommentstringopcional
Facebook: text posted as the first comment.
facebookPublishAs"default" | "reel" | "carousel" | "suppress_link"opcional
Facebook format.
facebookCarouselCardsobject[]opcional
Facebook carousel cards (when facebookPublishAs is carousel), each { headline, description, link }.
descriptionstringopcional
facebookTargetCountrystringopcional
Facebook audience restriction: country code.
facebookTargetGenderstringopcional
Facebook audience restriction: gender.
facebookTargetAgeMinstringopcional
Facebook audience restriction: minimum age.
facebookTargetAgeMaxstringopcional
Facebook audience restriction: maximum age.
facebookTargetRelationshipstringopcional
Facebook audience restriction: relationship status.
instagramFirstCommentstringopcional
Instagram: text posted as the first comment.
instagramAltTextstringopcional
Instagram: alt text for the image.
xReplySettings"everyone" | "following" | "mentioned"opcional
X: who can reply.
linkedinVisibility"anyone" | "connections" | "followers"opcional
LinkedIn: who can see the post.
linkedinFirstCommentstringopcional
LinkedIn: text posted as the first comment.
pinterestTitlestringopcional
Pinterest: pin title.
pinterestBoardIdstringopcional
Pinterest: board to pin to (see list_pinterest_boards).
pinterestBoardNamestringopcional
Pinterest: board name, for display.
pinterestLinkstringopcional
Pinterest: destination link of the pin.
pinterestAltTextstringopcional
Pinterest: alt text for the pin image.
mastodonVisibility"public" | "unlisted" | "private" | "direct"opcional
Mastodon: visibility.
mastodonSpoilerTextstringopcional
Mastodon: content-warning text.
mastodonSensitivebooleanopcional
Mastodon: mark media as sensitive.
blueskyLanguagestringopcional
Bluesky: language code of the post, e.g. en.
blueskyReplyGating"everyone" | "mentioned" | "following" | "nobody"opcional
Bluesky: who can reply.
draftbooleanopcional
Save as draft without publishing. Drafts skip publish-gating 'required' checks (required message, required media, required event/offer fields) but STILL enforce structural checks: character limits, media counts, media mixing, valid enums, carousel bounds, and date ordering.