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

Create up to 100 drafts or schedules

Idempotent per batch_id + item_key: retry an identical request after a timeout. Changing an item while keeping its key is a conflict. Bulk cannot publish immediately. Media must be managed uploads referenced by asset_id.

POST/api/cli/posts/bulk
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
batch_idstring<uuid>required
itemsobject[]required
min items 1 · max items 100
Show properties
Array of object
item_keystringrequired
max length 100 · matches ^[a-zA-Z0-9][a-zA-Z0-9._:-]*$
titlestringrequired
max length 120
captionstringrequired
max length 2200
media_typestringrequired
Allowed:imagecarouselvideo
mediaobject[]required
min items 1 · max items 10
Show properties
Array of object
asset_idstring<uuid>required
textstring
max length 500
aspect_ratiostring
targetsTarget[]
max items 12
Show properties
Array of Target
social_account_idstring<uuid>required
platformPlatformrequired
Allowed:tiktokinstagramyoutubelinkedinx
settingsobject
actionstringrequired
Allowed:draftschedule
scheduled_atstring<date-time>
cover_msinteger

Video items only. Cover frame in milliseconds, as cover_ms on single posts.

min 0 · max 3600000
cover_asset_idstring<uuid>

Video items only. Asset id of a completed JPEG or PNG upload used as the cover, as cover_url on single posts.

Responses
201

Created

batch_idstring<uuid>
itemsobject[]
totalinteger
has_moreboolean
warningsstring[]
nextstring
400

Invalid batch

errorstringrequired
codestring
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
409

Idempotency conflict

errorstringrequired
codestring
Try it
Server
Authorization
Bodyapplication/json
Request
curl -X POST "https://www.brainyshorts.com/api/cli/posts/bulk" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "batch_id": "4da22c97-b7d5-4e31-8c3a-03870ebc7b20",
  "items": [
    {
      "item_key": "string",
      "title": "string",
      "caption": "string",
      "media_type": "image",
      "media": [
        {
          "asset_id": "b4695157-0d1d-4da0-8f9e-5c53149389e4",
          "text": "string",
          "aspect_ratio": "string"
        }
      ],
      "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_asset_id": "6bd8f503-67d9-4b55-b7c3-e1b6bef82750"
    }
  ]
}'
Response
{
  "batch_id": "4da22c97-b7d5-4e31-8c3a-03870ebc7b20",
  "items": [
    {}
  ],
  "total": 0,
  "has_more": true,
  "warnings": [
    "string"
  ],
  "next": "string"
}