BulkPublish

Abort an in-progress chunked upload and free its stored parts. Use this when a chunked upload should be cancelled and its stored parts freed.

Approve a post awaiting team approval. Requires a role with post:approve (owner, admin, approver). Releases a post with approvalStatus 'pending': it publishes at its scheduled time, or immediately if that time has already passed. The author is notified in-app. Errors: 400 if the post is not awaiting approval, 403 if the role lacks post:approve, 404 if not found. Use this when the user (an owner/admin/approver) wants to approve a post awaiting team approval.

Perform a bulk action on multiple posts. Supports deleting, retrying, or rescheduling multiple posts at once. Use this when the user wants to delete, retry, or reschedule many posts in a single request.

Complete a chunked upload: the server assembles the uploaded parts, verifies the stored object (existence, size, magic bytes, storage quota) and records the media file — same verification and response shape as finalize_media_upload. A failed assembly automatically aborts the upload. Use this when all parts of a chunked upload are PUT and their ETags collected.

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.

Create a channel set — a saved channel grouping for one-click multi-channel targeting. Names are unique per organization (a duplicate fails with a 409, code DUPLICATE_NAME); an organization can have up to 50 sets. Use this when the user wants to save a group of channels for one-click targeting.

Create a new label for organizing posts or media files. Use this when the user wants a new label/tag.

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).

Start a chunked (multipart) direct-to-storage upload for large media — videos up to 1GB, images up to 100MB. Returns r2Key, uploadId, the fixed partSize (10485760 bytes = 10MB), and one presigned PUT URL per part (valid 3600s). PUT each 10MB slice to its URL, collect each response's ETag header, then call complete_multipart_upload. For ordinary files prefer upload_media. Use this when a file is too large for a single upload (e.g. a video over 100MB, up to 1GB) and must be sent in 10MB chunks.

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).

Add an RSS autopost feed. The feed is polled every 15 minutes and new items become posts on the chosen channels. The server validates that feedUrl is a reachable public RSS 2.0 or Atom feed. An organization can have up to 20 feeds. Use this when the user wants new items from an RSS/Atom feed to become posts automatically.

Create a new recurring post schedule. Posts are automatically created and published on the chosen frequency. The schedule is visible in the web app (Repeat Posts page, with upcoming runs on the Calendar); a post record exists only once an occurrence fires, carrying recurringScheduleId. Use this when the user wants a recurring posting schedule.

Delete a channel set by ID. Does not affect the channels themselves. Use this when the user wants to remove a saved channel set.

Delete a label by ID. Removes the label from all associated posts or media. Use this when the user wants to delete a label.

Delete a media file by ID. Removes the file from storage and detaches it from any posts. Use this when the user wants to delete a media file.

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

Delete an RSS autopost feed by ID. Stops polling; already-created posts are kept. Use this when the user wants to stop and remove an RSS autopost feed.

Delete a recurring schedule by ID. Stops all future posts from this schedule. Use this when the user wants to stop and delete a recurring schedule.

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).

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.

Check the health status of a connected channel. Returns token validity, connection status, and any issues. Use this when the user asks whether a channel's connection/token is healthy.

Get platform-specific options for a channel (e.g. available post types, character limits, media requirements). Use this when you need a platform's valid post types before creating a post for it.

Get details of a single media file by ID. Returns metadata, URL, dimensions, and labels. Use this when the user references one specific media file by ID.

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.

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; YouTube reports no shares or reach; Reddit reports likes (score), comments and shares (crossposts); Discord reports likes (reaction counts) and comments (thread replies); Google Business, Telegram, Tumblr and LinkedIn personal profiles report nothing readable at all. Each platform entry also carries linkClicks (summed in totals.linkClicks): clicks on bulkpubli.sh short links in this post, measured by BulkPublish rather than reported by the platform. It sits OUTSIDE latest and is distinct from the platform's own clicks — one visit can register in both, so never add them together. It is therefore available even for the platforms that report nothing, and supportedMetrics always includes it. Bot and link-preview traffic is excluded; it is 0 for organizations without Link Tracking enabled. Use this when the user asks how a specific post performed (likes, views, engagement).

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.

Check current account usage. Returns daily/monthly post counts, scheduled post counts, channel counts, and media storage usage. Also returns channelSlots — purchased extra channel slots ($2.99/month each, available on every plan; a seat-based subscription whose unused slots are auto-canceled before renewal): each active slot raises the effective total channel limit by one and allows one channel above the per-platform cap; per-slot autoRenews says whether it renews or lapses at expiresAt. Use this when the user asks about plan limits or current usage.

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.

List saved channel sets — named channel groupings for one-click multi-channel targeting. Returns id, name, and channelIds for each set, ordered by name. Use this when the user wants their saved channel groups (channel sets).

List all labels available for tagging posts and media. Use this when the user wants their post labels/tags.

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.

List every social platform BulkPublish supports and whether it is currently available. Check this before telling a user they can connect a platform or scheduling a post to one: a platform in state 'off' rejects post creation with a 403 PLATFORM_DISABLED error and holds any already-scheduled posts until it is re-enabled, and one in state 'connect_off' cannot accept new connections although existing channels keep publishing. Disabled platforms are still listed, with enabled=false and a reason. A platform may also carry a 'variants' object keyed by channel accountType for sub-platforms gated on their own: LinkedIn reports variants.organization for company pages (a separate LinkedIn app with its own review), while the platform-level state covers personal profiles — so pages can be paused while personal-profile posting is live. A variant is never more permissive than its parent, and when a variant blocks a write the 403 PLATFORM_DISABLED error carries an accountType field naming it. Use this when the user asks which platforms are supported or available, or a connect/publish attempt failed with PLATFORM_DISABLED.

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).

List RSS autopost feeds — RSS/Atom feeds polled every 15 minutes whose new items automatically become posts. Returns name, feedUrl, channelIds, mode, fieldMapping (how items are rendered into posts; null = default), enabled, lastCheckedAt, and lastError for each feed. Use this when the user wants their RSS autopost feeds.

List all recurring post schedules. Returns schedule name, frequency/timeOfDay timing fields, target channels, active status, and nextRunAt. These schedules also appear in the web app: managed on the Repeat Posts page, with upcoming runs shown on the Calendar. Use this when the user wants their recurring posting schedules.

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.

Publish a post as a story on Facebook or Instagram. Use this when the user wants to post an Instagram/Facebook story.

Reject a post awaiting team approval. Requires a role with post:approve. The post returns to draft with approvalStatus 'rejected' and the optional reason; the author is notified and can edit + reschedule to resubmit for approval. Errors: 400 if the post is not awaiting approval, 403 if the role lacks post:approve, 404 if not found. Use this when the user (an owner/admin/approver) wants to reject a post awaiting team approval, optionally with a reason.

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 pass republish: true after they confirm the post is not live. Use this when a post failed on some platforms and the user wants to retry just those.

Search for @mention suggestions on a channel. Useful for finding users/pages to mention in posts. Use this when you need @mention suggestions from a connected channel while drafting a post.

Update a channel set's name and/or channels (partial update — at least one field is required). A name that collides with another set fails with a 409, code DUPLICATE_NAME. Use this when the user wants to rename a channel set or change its channels.

Update an existing label's name or color. Use this when the user wants to rename or recolor a label.

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.

Update an RSS autopost feed (partial update). Note: changing feedUrl re-baselines the feed — its check state resets and only items published after the change are posted, so the new feed's backlog is not flooded. Use this when the user wants to change, pause, or re-point an RSS autopost feed.

Update an existing recurring schedule. Can change name, content template, frequency/timing, timezone, media, or active status. The next run time is recomputed by the server when timing changes. Use this when the user wants to change a recurring schedule.

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.

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.

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.

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

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.

Open an interactive view of current account usage — daily/monthly post counts, channel counts, and media storage. Use this when the user wants a visual view of their plan usage.