Create a post
Creates a draft, a scheduled post, or an immediate post. If action is omitted the post is a draft (or scheduled when scheduled_at is present); it is never published unless you send action: "publish". Media is required: send at least one HTTPS URL in media_urls (use the public_url of a managed upload). Publish only when the user asked for it now. YouTube targets publish now or on a schedule from an MP4 uploaded to Brainy Shorts (reserve the upload, PUT the file, complete it, then use its public_url), up to 200 MiB. They upload as public unless settings.privacy_status is private or unlisted. Legacy aliases still accepted: integrations for targets, scheduled_time for scheduled_at.
/api/cli/postsAuthorizationBearer token (ba_sk_...) · headerrequiredAPI key from /dashboard/api-keys. Keys expire after 365 days.
AuthorizationBearer token (ba_mcp_access_...) · headerrequiredThe OAuth access token the hosted MCP server issues (brainy:read for GET routes, brainy:write for everything else). One login serves MCP, the CLI and the desktop app. A token without the needed scope gets 403 Insufficient scope.
application/jsontitlestringDefaults to the first 120 characters of the caption
captionstringrequiredX targets limit the caption to 280 characters
media_typestringInferred when omitted. image: 1 URL; carousel: 2+; video: 1 MP4.
imagecarouselvideomedia_urlsstring<uri>[]JSON array of HTTPS URLs, not a comma-separated string. At least one is required. TikTok photo posts take up to 10.
slidesSlide[]Show propertiesHide properties
Slidetextstringurlstring<uri>requiredaspect_ratiostringtargetsTarget[]Show propertiesHide properties
Targetsocial_account_idstring<uuid>requiredplatformPlatformrequiredtiktokinstagramyoutubelinkedinxsettingsobjectactionstringDefaults to draft when omitted (or schedule when scheduled_at is set). Never publishes unless publish is sent. YouTube targets need a completed Brainy Shorts MP4 upload to publish or schedule.
draftpublishschedulescheduled_atstring<date-time>Required for schedule; must be in the future. scheduled_time is accepted as an alias.
cover_msintegerVideo posts only. Frame offset in milliseconds used as the cover on TikTok (video_cover_timestamp_ms) and Instagram Reels (thumb_offset). LinkedIn and X ignore it; the response's notes says so.
cover_urlstring<uri>Video posts only. public_url of a completed Brainy Shorts JPEG or PNG upload. Used as the Instagram Reels cover (JPEG) and the YouTube thumbnail (2 MB max; YouTube requires a verified channel, and a refused thumbnail never fails the post). TikTok uses only cover_ms.
Created. Body is {post, social_posts}: the parent post and one delivery per target.
postobjectParent post
social_postsobject[]One delivery per target
Invalid post
errorstringissuesobjectMissing, invalid, expired, or revoked API key
errorstringrequiredcodestringMonthly post allowance used up. Save as a draft, schedule for a later month, or upgrade at upgrade_url.
errorstringrequiredcodestringrequiredupgrade_urlstring<uri>requiredlimitintegerusedintegerrequestedintegerperiodstringUTC month, YYYY-MM
planstring