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
}
]
}
summaryadds up only the returnedposts, which is at mostlimitposts. It is not an account total. Its keys aretotal_postsplus camel-casetotalViews,totalLikes,totalComments, andtotalShares; each post usesviews,likes, and so on.post_idis the id of the synced platform post. It is not theidorpost_idthatPOST /postsorGET /postsreturned, so you cannot look up a scheduled post’s metrics with them. Read it from this endpoint’s ownpostslist.GET /analytics?post_id=<post_id>returns that one post, with the same fields and ametricsobject 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.
