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 (`{"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 by platform, account, post, and date

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 HTTPS URLs, up to 10. A comma-separated string is rejected.
`targets`	Up to 12 `{ social_account_id, platform, settings? }`
`action`	`draft`, `schedule`, or `publish`
`scheduled_at`	ISO 8601 with offset, in the future. `scheduled_time` is accepted as an alias.

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

The response is 201 with { "post": {...}, "social_posts": [...] }, one delivery per target.

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

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 removes a post in draft, scheduled, retry_scheduled, or failed status. Published posts can’t be deleted through the API.

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
`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)
`410`	Removed hosted-processing endpoint; see below
`429`	Media storage quota exceeded (`MEDIA_STORAGE_QUOTA_EXCEEDED`)

Removed endpoints

BrainyShorts no longer generates or processes media on its servers. These endpoints return 410 Gone with a pointer to the replacement:

POST /api/cli/upload: use /api/cli/media/uploads
POST /api/cli/generate-photo-content: generate with your own agent, then create a post