Create post
create_postCreate 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).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| labels | No | Array of label IDs to tag the post with. | |
| status | No | Post status. "draft" (default) or "scheduled". | |
| content | No | The post text content. Optional — defaults to empty for media-only posts. LinkedIn mentions: write @[Display Name](urn:li:organization:ID) for a Page or @[Display Name](urn:li:person:ID) for a person; search_mentions on a LinkedIn channel returns ready-made Page tokens. The token publishes as a real mention on LinkedIn and as plain @Display Name on other channels. | |
| channels | Yes | Array of channels to post to. Get channel IDs from list_channels. | |
| timezone | No | Timezone for scheduling (e.g. "America/New_York"). Defaults to UTC. | |
| postFormat | No | Post format. "post" (default), "video", "reel", "story", "carousel", or "thread" for multi-part threads. | |
| scheduledAt | No | ISO 8601 datetime for scheduling (e.g. 2025-01-15T10:00:00Z). Required when status is scheduled. | |
| threadParts | No | Thread parts array. Required when postFormat is thread (min 2 parts). EVERY part is measured against the character limit of every platform the post targets, not only the first — an over-long part is rejected with 400 VALIDATION_ERROR naming the part number, the platform and its limit. URLs count as 23 characters on X and Mastodon, their real length elsewhere. | |
| mediaFileIds | No | Array of media file IDs to attach. Upload media first with upload_media. | |
| platformContent | No | Per-platform content overrides, e.g. { "x": "Short tweet", "linkedin": "Longer LinkedIn post" }. | |
| requestApproval | No | Optional (default false). Set true to hold a scheduled post for team approval (approvalStatus becomes 'pending'). Forced on server-side for API keys of roles without post:publish (contributors), regardless of this flag. | |
| platformSpecific | No | Platform-specific settings, e.g. { "youtube": { "title": "…", "privacyStatus": "public" } }. Reddit, Discord, Tumblr and Snapchat nest their options under the BulkPublish channel id, e.g. { "reddit": { "12": { "subreddit": "webdev" } } }. Telegram takes no options. | |
| postTypeOverrides | No | Per-platform post type override. E.g. { "instagram": "reel", "youtube": "short" }. | |
| publishWhenApproved | No | Optional (default false). Set true on a post that waits for approval when it should go out as soon as it is approved, even if that is after its scheduled time. This is how someone who needs approval says 'publish now': status 'scheduled', scheduledAt = now, requestApproval true (or a contributor key), publishWhenApproved true. An approval arriving more than 15 minutes late then publishes immediately; with false it is approved but returned to draft for a new time. Stored only when the post ends up approvalStatus 'pending'; otherwise saved as false. | |
| linkTrackingOverride | No | Optional per-post override for link tracking (bulkpubli.sh). true forces links in this post to be shortened and their clicks counted, false forces them to publish as written, and null/omitted (the default) inherits the organization's Link Tracking setting. Shortening happens at publish time, per channel, so two accounts on the same platform get distinct codes; it is skipped for a channel when the rewrite would push the post past that platform's character limit (a short URL is 28 characters and can be longer than the link it replaces). |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | ||
| author | No | Who wrote the post: { id, name, image }. Null when that account is gone. | |
| labels | No | ||
| status | No | draft, scheduled, processing, published, partial or failed. | |
| content | No | ||
| approver | No | Who approved it: { id, name, image }. Null unless approvalStatus is approved. | |
| assignee | No | Who is expected to act on it next: { id, name, image }. Null when nobody is. | |
| timezone | No | ||
| createdAt | No | ||
| mediaFiles | No | ||
| publishedAt | No | ||
| scheduledAt | No | ||
| postPlatforms | No | ||
| approvalStatus | No |