BulkPublish

List channels

List all connected social media channels (X/Twitter, Instagram, LinkedIn, Facebook, TikTok, etc.). Returns channel ID, platform, account name, and token status. Use this when the user wants to see which social accounts are connected.

Create post

Create a new social media post. Can be saved as a draft or scheduled for a specific time. Supports platform-specific content overrides, media attachments, labels, and thread format. IMPORTANT: YouTube and TikTok REQUIRE video — do not include them when posting images only. Instagram defaults to feed_photo — set postTypeOverrides for video content (reel, feed_video). Use this when the user wants to draft or schedule one new post (do not publish immediately unless asked).

List posts

List posts with optional filters for status, search text, date range, channel, and label. Returns paginated results with platform statuses and metrics, ordered newest-first by publishedAt if the post is live, else scheduledAt, else createdAt. Use this when the user wants to browse, filter, or check the status of existing posts as raw data (not the visual dashboard).

Get post

Get a single post by ID with full details including platform statuses, labels, media files, recurring schedule info, and metrics. Use this when the user references one specific post by its ID.

Publish post now

Publish a draft or scheduled post immediately. The post will be queued for publishing to all its target channels. Requires a role with post:publish — contributors get 403 APPROVAL_REQUIRED and must submit the post for approval instead (create/update with requestApproval, then a teammate approves). Publishing a pending/rejected post as an approver implicitly approves it. Use this when the user wants to publish an existing draft or scheduled post right now.

Retry failed post

Retry publishing a failed or partially failed post. Only retries the platforms that failed, not the ones that already succeeded. Platforms in status 'unconfirmed' (the publish request may have reached the platform but its response was lost — the post may already be live) are NOT retried unless republish is true; if the post has unconfirmed platforms and no failed ones, the call fails with a 400 and code UNCONFIRMED_REQUIRES_REPUBLISH — ask the user to check the account on the platform, and only

Upload media

Upload a media file (image or video) from a URL or local file path. The file is stored in BulkPublish for use in posts. Supported formats: JPEG, PNG, WebP, GIF, MP4, MOV, WebM. Max 100MB. Provide either url OR filePath, not both. Use this when the user provides an image/video to attach to a post.

List media

List uploaded media files with optional search and pagination. Returns file metadata including URLs, dimensions, and labels. Use this when the user wants a list of their uploaded media files.

Get analytics

Get an analytics summary for a date range. Returns total posts, status breakdown (published, failed, scheduled), per-platform stats, and daily post counts. Use this when the user asks how their content performed overall, across channels and over a date range.

Update post

Update an existing post. Can change content, schedule, media, labels, status, and platform-specific settings. Only draft, scheduled, failed, or partial posts can be edited; editing a failed/partial post resets it to draft. Set status to 'draft' or 'scheduled' to move the post between those states — use publish_post to publish immediately. Use this when the user wants to edit an existing post.

Delete post

Delete a post by ID. Only draft and failed posts can be deleted. Use this when the user wants to permanently remove a post.

Get post metrics

Get engagement metrics for a published post. Returns likes, comments, shares, impressions, and other platform-specific metrics. IMPORTANT: every platform entry carries `metricsSupported` and `supportedMetrics` — a metric key NOT in `supportedMetrics` is stored as 0 because that platform's API has no such field, so report it as unavailable rather than as zero. X reports impressions/likes/comments/shares/saves (bookmarks); Bluesky and Mastodon report no impressions; Pinterest reports no reach; You

Get next queue slot

Get the organization's next available queue slot. Useful for finding the next optimal scheduling time. Use this when the user asks when the next available scheduling slot is.

Compose a post

Open an interactive composer to draft or schedule a social media post. Shows the user's connected channels to pick from and pre-fills any provided text. The user finishes in the UI; on submit it creates the post via create_post. Use this when the user wants to compose a post interactively in a UI — prefer this over create_post when they'd review before posting.

Analytics dashboard

Open an interactive analytics dashboard for a date range — totals, status breakdown, per-platform stats, and daily post counts. Use this when the user wants an interactive analytics dashboard — prefer over get_analytics for a visual view.

Posts

Open an interactive list of posts with their status, schedule, and channels. Optionally filter by status. Use this when the user wants to see their posts as an interactive dashboard — prefer over list_posts for a visual view.

Channels

Open an interactive view of connected social channels with platform, account, and connection/token status. Use this when the user wants an interactive view of their connected channels.

Media library

Open an interactive gallery of uploaded media files with thumbnails and metadata. Use this when the user wants to browse their media library visually.

Start media upload

Reserve a presigned R2 upload URL for a direct browser upload (used by the composer UI). For scripted uploads use upload_media instead. Use this when you need a presigned URL for a large direct upload (advanced; prefer upload_media for normal files).

Finalize media upload

Record an uploaded R2 object as a media file after the browser PUT (pairs with create_media_upload; used by the composer UI). Use this when a presigned direct upload finished and the file must be registered (advanced).