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

REST API

Base URL, authentication, request conventions, and the main endpoints of the BrainyShorts REST API.

The REST API is the base every other surface builds on. The CLI calls it, and the MCP server exposes the same operations as tools.

Base URL https://www.brainyshorts.com/api/cli
Auth Authorization: Bearer ba_sk_... (Authentication)
Format JSON in and out; send Content-Type: application/json
Spec /openapi.json, also browsable under API reference

Endpoints

Method Path Purpose
GET /accounts Connected social accounts
GET /posts?status=&platform=&limit= List post deliveries (max 100)
POST /posts Create a draft, scheduled, or immediate post
PATCH /posts Edit or reschedule a draft or scheduled post
DELETE /posts Delete a draft, scheduled, or failed post by delivery id ({"id": "..."})
POST /posts/bulk Create up to 100 drafts or schedules idempotently
GET /posts/bulk?batch_id=&offset=&limit= Batch status
PATCH /posts/bulk Update up to 100 scheduled posts
POST /media/uploads Reserve a managed upload
PATCH /media/uploads Complete a managed upload
GET /articles List long-form articles
POST /articles Create, schedule, or publish an article
DELETE /articles Delete an article ({"id": "..."})
GET /analytics Metrics for synced published posts, by platform, account, post, and date (details)
GET /usage Plan, posts used this month, and connected-account allowance
POST /billing/checkout Stripe Checkout link for a paid plan ({"plan": "creator"} or "pro")

Skills and runner endpoints live elsewhere: see Skills and Scheduled runs.

Creating a post

{
  "title": "Launch teaser",
  "caption": "Something new is coming.",
  "media_type": "video",
  "media_urls": ["https://storage.brainyshorts.com/..."],
  "targets": [{ "social_account_id": "3f0c...", "platform": "instagram" }],
  "action": "schedule",
  "scheduled_at": "2026-10-01T17:00:00Z"
}
Field Rules
title 1–120 characters. Defaults to the start of the caption.
caption 1–2,200 characters (280 when an X target is present)
media_type image (exactly 1 URL), carousel (2–10), or video (exactly 1). Inferred when omitted.
media_urls JSON array of 1–10 HTTPS URLs. Required for every post, drafts included. A comma-separated string is rejected. TikTok photo posts take up to 10.
targets Up to 12 { social_account_id, platform, settings? }
action draft, schedule, or publish. Omit it for a draft.
scheduled_at ISO 8601 with offset, in the future. scheduled_time is accepted as an alias.

Omit action and the post is a draft, the same as the CLI and the MCP server. If you set scheduled_at without an action, it is scheduled. Nothing is published unless you send "action": "publish". 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. Video posts can set a cover: cover_ms (the frame, in milliseconds) is used by TikTok and Instagram Reels, and cover_url (a JPEG or PNG uploaded to Brainy Shorts) is used as the Instagram Reels cover and the YouTube thumbnail. LinkedIn and X ignore covers, and the response’s notes says what a platform did not use.

The legacy integrations field is still accepted in place of targets.

The response is 201 with { "post": {...}, "social_posts": [...] }: the parent post (post.id) and one delivery per target (social_posts[].id).

Media URLs

Upload through /media/uploads (see the Quickstart) and use the returned public_url. You can also pass your own durable HTTPS URL, but several platforms only pull from verified domains. TikTok, for example, rejects URLs outside storage.brainyshorts.com. Temporary model-output URLs such as replicate.delivery are rejected.

Editing and deleting

GET /posts returns one row per delivery, with id (the delivery id) and post_id (the parent post id).

PATCH /posts takes id (either the parent post id or any delivery id) plus at least one of caption, scheduled_at, or add_targets. Send status: "draft" instead to unschedule. Every still-scheduled delivery under the parent changes together.

DELETE /posts takes a delivery id (the id from GET /posts), not the parent post id, and removes it only in draft, scheduled, retry_scheduled, or failed status. Published posts can’t be deleted through the API and return 409.

Analytics

GET /analytics returns metrics for published posts that BrainyShorts has already synced from the platforms, newest first. Filters: platform, account_id, start_date, end_date, and limit (default 20, max 100).

{
  "summary": { "total_posts": 2, "totalViews": 1520, "totalLikes": 88, "totalComments": 9, "totalShares": 4 },
  "posts": [
    {
      "post_id": "8d1f...",
      "platform_post_id": "17895695668004550",
      "social_account_id": "3f0c...",
      "platform": "instagram",
      "title": "Launch teaser",
      "posted_time": "2026-10-01T17:00:00Z",
      "platform_url": "https://...",
      "views": 1200, "likes": 70, "comments": 6, "shares": 3, "saves": 11
    }
  ]
}
  • summary adds up only the returned posts, which is at most limit posts. It is not an account total. Its keys are total_posts plus camel-case totalViews, totalLikes, totalComments, and totalShares; each post uses views, likes, and so on.
  • post_id is the id of the synced platform post. It is not the id or post_id that POST /posts or GET /posts returned, so you cannot look up a scheduled post’s metrics with them. Read it from this endpoint’s own posts list.
  • GET /analytics?post_id=<post_id> returns that one post, with the same fields and a metrics object in place of the flat counts.
  • LinkedIn metrics need a separate analytics consent from the account owner.

Articles

{
  "title": "How we cut build times in half",
  "markdown": "# ...",
  "tags": ["devops", "ci"],
  "canonical_url": "https://example.com/blog/builds",
  "targets": [
    { "social_account_id": "...", "platform": "devto" },
    { "social_account_id": "...", "platform": "reddit", "settings": { "subreddit": "programming" } }
  ],
  "action": "publish"
}

Article action defaults to draft. With publish, delivery happens inline and the response includes per-destination results with the live URLs. Platforms are devto, hashnode, reddit, linkedin, and x; see Platforms.

Errors

Errors are JSON with an HTTP status:

{ "error": "Human-readable message", "code": "MACHINE_CODE" }

Validation failures return 400 with the field-level problems:

{ "error": "Invalid post", "issues": { "formErrors": [], "fieldErrors": { "scheduled_at": ["scheduled_at must be in the future"] } } }
Status Meaning
400 Invalid body; read issues
401 Missing, malformed, expired, or revoked key, or a key without the scope the endpoint needs
402 Monthly post allowance used up (QUOTA_EXCEEDED); see below
404 The resource does not exist or isn’t yours. Unknown /api/... paths also return JSON 404s with links to these docs.
409 Idempotency conflict (bulk item reused with different content)
429 Media storage quota exceeded (MEDIA_STORAGE_QUOTA_EXCEEDED)

Monthly post allowance

On the Free plan, creating, scheduling, or publishing a post that would go past the month’s allowance returns 402:

{
  "error": "The Free plan includes 30 posts a month, and October 2026 is full. ...",
  "code": "QUOTA_EXCEEDED",
  "upgrade_url": "https://www.brainyshorts.com/dashboard/billing",
  "limit": 30,
  "used": 30,
  "requested": 1,
  "period": "2026-10",
  "plan": "Free"
}

Drafts never count, so saving as a draft always works. You can also schedule the post for a later month, or ask the user to upgrade. GET /usage shows what’s left before you try. See Limits and pricing.

Was this page helpful?