Posts

Create, publish, and analyze social posts, including boosted posts.

• Writecreate_postCreate a post for a location (or client) and submit it to the selected platforms. Publishes immediately unless scheduledFor is set or draft is true. A requested platform with no active connection never fails this call — the post is still created (as a draft if nothing resolved), and the response is `{ status: "no_connection", missingPlatforms, scope, post: { id, status } }` instead of the usual `{ id, status }` for whichever platforms couldn't resolve a connection. Compose what to tell the user from that data; do not assume the call failed just because `status` is "no_connection" — the content was saved. Likewise a post that cannot go live yet because a REQUIRED FIELD is absent (an event with no start/end date, a caption-less announcement, Instagram with no image) is saved as a draft and answers `{ status: "incomplete", missingFields, scope, post }`. Both gaps can appear together, in which case `status` is "no_connection" and `missingFields` rides alongside it — tell the user about BOTH at once rather than letting them discover the second after fixing the first. In every one of these cases the content EXISTS as a draft: say what was saved, name what it needs, point at where to fix it, and never report it as a failure. PLATFORM RULES (enforced — violations rejected): Post types: `announcement` works on every platform; `event` and `offer` are Google-only (any social platform ⇒ must be announcement). Caption char limits: google 1500, facebook 30000, instagram 2200, x 280 (X thread mode is exempt from the 280 limit), linkedin 2000, pinterest 500, mastodon 500, bluesky 300. Media (per platform, using each item's `platform`): facebook ≤10 images OR ≤1 video, no mix (carousel = 2–10 images only, per-card headline ≤80 / description ≤200); instagram requires ≥1 media, ≤10 images OR ≤1 video, no image/video mix; x ≤4 images OR ≤1 video, no mix; linkedin ≤5 images OR ≤1 video, no mix; pinterest image-only, exactly 1, required; mastodon ≤4 images OR ≤1 video, no mix. Google event ⇒ eventTitle (≤58 chars) + eventStartAt + eventEndAt (end after start) required. Google offer ⇒ ctaType + ctaUrl required. scheduledFor must be in the future. Drafts (draft=true) skip required-field checks but still enforce all structural checks above.
• Writeupdate_postUpdate an editable post (draft/scheduled/error/active). Reconciles platform submissions. A requested platform with no active connection never fails this call either (same as create_post) and the response is `{ status: "no_connection", missingPlatforms, scope, post: { id, status } }` instead of the usual `{ id, status }`. PLATFORM RULES (enforced — violations rejected): Post types: `announcement` works on every platform; `event` and `offer` are Google-only (any social platform ⇒ must be announcement). Caption char limits: google 1500, facebook 30000, instagram 2200, x 280 (X thread mode is exempt from the 280 limit), linkedin 2000, pinterest 500, mastodon 500, bluesky 300. Media (per platform, using each item's `platform`): facebook ≤10 images OR ≤1 video, no mix (carousel = 2–10 images only, per-card headline ≤80 / description ≤200); instagram requires ≥1 media, ≤10 images OR ≤1 video, no image/video mix; x ≤4 images OR ≤1 video, no mix; linkedin ≤5 images OR ≤1 video, no mix; pinterest image-only, exactly 1, required; mastodon ≤4 images OR ≤1 video, no mix. Google event ⇒ eventTitle (≤58 chars) + eventStartAt + eventEndAt (end after start) required. Google offer ⇒ ctaType + ctaUrl required. scheduledFor must be in the future. Drafts (draft=true) skip required-field checks but still enforce all structural checks above.
• Readget_postGet a post with per-platform submission performance (agency-scoped).
• Readlist_postsList posts for a location with per-platform state and aggregate stats (agency-scoped).
• Writedelete_postDelete a post and unpublish it from its platforms. Unpublishes every platform first, then archives the post ONLY IF every platform unpublish succeeded — this never permanently deletes the row; it just stops appearing anywhere in the API. If even one platform fails to unpublish, nothing is archived — the call still succeeds (no throw) but returns `ok: false` with a `failed` list; check `ok` rather than assuming the post is gone.
• Writepublish_post_nowForce-submit a draft/errored post now (retries pending/errored platform submissions). Throws if the post is scheduled for a future time — cancel or wait for the schedule instead. A no-op (no error, nothing retried) if there's nothing pending or errored to retry.
• Readget_post_analyticsSee how posts are performing — engagement, views, clicks, impressions over time. Read-only analytics rollup across a client's brand connections (summary, byPlatform, trends, top posts).
• Readget_posts_client_rollupPosts "All locations" rollup for a client — the stat cards + location health breakdown shown when a client is selected with no specific location. Returns locationCount, healthCounts (errors / notSetUp / new / silent / quiet / active — mutually exclusive per-location classification based on connection errors, posting recency, and engagement), stats for the last 30 days (totalPosts, totalEngagement, totalImpressions, totalClicks, avgPostsPerWeek) with prevStats for the prior 30 days (for delta display), and missingBrandPlatforms (brand-level social platforms not yet connected for this client). Pass locationId to narrow the stat cards to one location while still reporting health counts for the whole client. Distinct from get_post_analytics (that one is trend charts/top posts); this is the health/rollup view.
• Writecreate_post_boostBoost a post with paid ad spend through a connected ad account — this spends real money. dailyBudget (minor currency units, e.g. cents) and durationDays are ALWAYS required, regardless of whether you also pass boostConfigId; if boostConfigId is given, only its adAccountId/targeting/publisherPlatforms/delayHours are used as defaults for whatever you don't specify — its own saved budget is never used silently. Pass postSubmissionId to boost an ALREADY-PUBLISHED post's live submission (spends immediately). Pass postId (+ platform or connectionId) instead to pre-configure a boost on a post that hasn't published yet — it stays queued (no spend) and only starts once that post's submission goes live. adAccountId must belong to a connected account (see list_ad_accounts); use select_ad_account first if none is selected.
• Writestop_post_boostStop a LIVE boost that's already spending on the platform — halts real in-flight ad spend. This cannot be resumed; a new boost would need to be created. To cancel a boost that hasn't gone live yet (still queued, awaiting the post to publish, no spend yet), use cancel_deferred_boost instead. Identify the boost by its adRunId — there is currently no tool to list/look one up; the only way to learn it is from create_post_boost's own response when the boost was created.
• Writecancel_deferred_boostCancel a deferred boost that hasn't gone live yet (its post hasn't published, so no money has been spent). To stop a boost that's already live and spending, use stop_post_boost instead. Identify it by its adCampaignId — there is currently no tool to list/look one up; the only way to learn it is from create_post_boost's own response when the deferred boost was created.