Skip to content
BrainyShorts Docs
Esc
↑↓navigate↵open⌘Jpreview

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.

POST/api/cli/posts
Authorization
AuthorizationBearer token (ba_sk_...) · headerrequired

API key from /dashboard/api-keys. Keys expire after 365 days.

or
AuthorizationBearer token (ba_mcp_access_...) · headerrequired

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

Request body
requiredapplication/json
titlestring

Defaults to the first 120 characters of the caption

max length 120
captionstringrequired

X targets limit the caption to 280 characters

min length 1 · max length 2200
media_typestring

Inferred when omitted. image: 1 URL; carousel: 2+; video: 1 MP4.

Allowed:imagecarouselvideo
media_urlsstring<uri>[]

JSON array of HTTPS URLs, not a comma-separated string. At least one is required. TikTok photo posts take up to 10.

max items 10
slidesSlide[]
max items 10
Show properties
Array of Slide
textstring
max length 500
urlstring<uri>required
aspect_ratiostring
default: "9:16"
targetsTarget[]
max items 12
Show properties
Array of Target
social_account_idstring<uuid>required
platformPlatformrequired
Allowed:tiktokinstagramyoutubelinkedinx
settingsobject
actionstring

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

Allowed:draftpublishschedule
scheduled_atstring<date-time>

Required for schedule; must be in the future. scheduled_time is accepted as an alias.

cover_msinteger

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

min 0 · max 3600000
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.

Responses
201

Created. Body is {post, social_posts}: the parent post and one delivery per target.

postobject

Parent post

social_postsobject[]

One delivery per target

400

Invalid post

errorstring
issuesobject
401

Missing, invalid, expired, or revoked API key

errorstringrequired
codestring
402

Monthly post allowance used up. Save as a draft, schedule for a later month, or upgrade at upgrade_url.

errorstringrequired
codestringrequired
upgrade_urlstring<uri>required
limitinteger
usedinteger
requestedinteger
periodstring

UTC month, YYYY-MM

planstring
Try it
Server
Authorization
Bodyapplication/json
Request
curl -X POST "https://www.brainyshorts.com/api/cli/posts" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "string",
  "caption": "string",
  "media_type": "image",
  "media_urls": [
    "http://example.com"
  ],
  "slides": [
    {
      "text": "string",
      "url": "http://example.com",
      "aspect_ratio": "9:16"
    }
  ],
  "targets": [
    {
      "social_account_id": "f4777757-36aa-48ee-b520-6e818e68eb51",
      "platform": "tiktok",
      "settings": {}
    }
  ],
  "action": "draft",
  "scheduled_at": "2019-08-24T14:15:22Z",
  "cover_ms": 0,
  "cover_url": "http://example.com"
}'
Response
{
  "post": {},
  "social_posts": [
    {}
  ]
}