Skip to navigation

Social · Posts · Create a social media post

View as Markdown

Schedule, queue, publish now, or draft a social media post. Publishing actions (‘schedule’, ‘add_to_queue’, ‘publish_now’) require at least one account in account_ids; ‘draft’ can be saved without any account. ‘publish_now’ is asynchronous: read the outcome with the single-post status tool, using the returned id. For a self-hosted WordPress blog post, pass the article as message and its title in additional.wordpress.post (see WordpressPost). For a Shopify blog article, pass the article as message and its title in additional.shopify.article (see ShopifyArticle). Optionally attach auto-comments via comments: a list of { "message": string, "delay": seconds } objects published after the post goes live, in array order. For a LinkedIn document (carousel) post, pass the PDF as additional.linkedin.document (see LinkedinDocument) with media: [].

Authentication

AuthorizationApi-Key

Header authentication of the form Api-Key <token>

OR
AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.
messagestringRequired<=100000 characters

Post text. Each network enforces its own limit server-side; WordPress and Shopify take a full article (WordPress in Markdown or HTML, Shopify in Markdown).

actionenumRequired

‘publish_now’ publishes immediately and asynchronously; date is ignored for it.

Allowed values:
account_idslist of stringsOptional

Target social media account IDs. Required for action ‘schedule’, ‘add_to_queue’ and ‘publish_now’. For action ‘draft’ this may be empty or omitted to create an accountless draft — note that an accountless draft keeps message, media, tags and comments but drops additional, so link a draft to an account whenever additional matters (WordPress and Shopify title, slug, excerpt, status).

datestringOptionalformat: "^\d{4}-\d{2}-\d{2} \d{2}:\d{2}$"

Scheduled datetime YYYY-MM-DD HH:MM, read in timezone when given, otherwise in the workspace timezone. Required for ‘schedule’.

medialist of strings or objectsOptional

Media items attached to the post. Each entry is a Simplified asset UUID, a fully qualified URL, or a { url, thumbUrl } object for video with an explicit poster/thumbnail — see MediaItem. Asset UUIDs are resolved server-side to a fresh permanent URL before publishing; pass them whenever the media was produced via generateImage with storage: "asset". URLs are passed through as-is and should only be used for media that already lives at a permanent public location.

tagslist of integersOptional

Tag (label) IDs to attach to the created post(s). Get IDs via listSocialMediaTags; create new ones via createSocialMediaTag. Tags are used by the user to filter posts in the Drafts/Publishing views and to deep-link the confirmation widget.

commentslist of objectsOptional

Optional auto-comments published to the post after it goes live, in array order. Omit or pass an empty array for no comments. Each entry exposes only message + delay (no media). delay is cast to an integer server-side; a comment with no message defaults to "".

additionalobjectOptional
timezonestringOptional

IANA timezone date is given in, e.g. Asia/Kolkata. Omit to use the workspace timezone.

originobjectOptional

Where the post came from, for a link back from the planner. Set project_id to the deliverable’s Project id. conversation_id and agent_slug are set automatically by the agent runtime.

Response

Post created successfully
idslist of anyOptional

Created planner post ids (draft ids for ‘draft’).