Social

One record holds every platform variant. Generate costs 0.6 credits per platform. Publish is free.

GET/api/v1/social/content

Returns a paginated list of your social media content records. Supports filtering by platform, status, source article, and project.

Query parameters

Name	Type	Required	Description
page	integer	Optional	Page number Default 1.
limit	integer	Optional	Results per page (1-100) Default 20.
platform	string	Optional	Filter to records that target this platform. One of the 10 supported values.
status	string	Optional	Filter by status: draft, queued, generating, ready, completed, scheduled, published, failed
article_id	uuid	Optional	Filter by source article ID
project_id	uuid	Optional	Filter by project ID

Request

curl "https://www.brainpercent.app/api/v1/social/content?platform=linkedin&status=completed&page=1&limit=10" \
  -H "Authorization: Bearer bp_your_key"

200Response

{
  "success": true,
  "data": [
    {
      "id": "c4a1e8b2-9f3d-4e7a-b5c6-1d2e3f4a5b6c",
      "article_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "project_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "title": "AI SEO strategies for 2026",
      "status": "completed",
      "source_url": "https://example.com/blog/ai-seo-strategies",
      "source_type": "blog",
      "language": "en",
      "platforms": {
        "linkedin": "Most teams treat SEO and AI as separate budgets. The ones winning in 2026 stopped doing that...",
        "instagram": "SEO in 2026 is a different sport. Swipe for the 5 shifts that actually moved our numbers."
      },
      "image_urls": {
        "linkedin": "https://xyz.supabase.co/storage/v1/object/public/social/linkedin-1.png",
        "instagram": "https://xyz.supabase.co/storage/v1/object/public/social/instagram-1.png"
      },
      "video_urls": {},
      "scheduled_publish_at": null,
      "error_message": null,
      "created_at": "2026-02-01T10:30:00Z",
      "updated_at": "2026-02-01T10:38:00Z"
    }
  ],
  "pagination": {
    "total": 15,
    "page": 1,
    "limit": 10,
    "total_pages": 2,
    "has_more": true
  }
}

GET/api/v1/social/content/:id

Returns the full record for a single social content item. Includes everything from the list response plus the source author, overlay images, first comments, thread items, the per-platform carousel plans, and publishing state.

Request

curl https://www.brainpercent.app/api/v1/social/content/CONTENT_ID \
  -H "Authorization: Bearer bp_your_key"

200Response

{
  "success": true,
  "data": {
    "id": "c4a1e8b2-9f3d-4e7a-b5c6-1d2e3f4a5b6c",
    "article_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "project_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "title": "AI SEO strategies for 2026",
    "status": "completed",
    "source_url": "https://example.com/blog/ai-seo-strategies",
    "source_type": "blog",
    "source_author": "Jane Doe",
    "language": "en",
    "platforms": {
      "linkedin": "Most teams treat SEO and AI as separate budgets...",
      "instagram": "SEO in 2026 is a different sport. Swipe for the 5 shifts..."
    },
    "image_urls": {
      "linkedin": "https://xyz.supabase.co/storage/v1/object/public/social/linkedin-1.png",
      "instagram": "https://xyz.supabase.co/storage/v1/object/public/social/instagram-1.png"
    },
    "overlay_urls": {},
    "video_urls": {},
    "first_comments": {
      "linkedin": "Full breakdown in the article linked in my profile."
    },
    "thread_items": [],
    "instagram_carousel_plan": [
      {
        "slide": 1,
        "headline": "SEO in 2026"
      }
    ],
    "linkedin_carousel_plan": [],
    "tiktok_carousel_plan": [],
    "facebook_carousel_plan": [],
    "twitter_carousel_plan": [],
    "threads_carousel_plan": [],
    "bluesky_carousel_plan": [],
    "telegram_carousel_plan": [],
    "processing_stage": "done",
    "processing_progress": 100,
    "is_published": false,
    "late_dev_post_id": null,
    "scheduled_publish_at": null,
    "error_message": null,
    "created_at": "2026-02-01T10:30:00Z",
    "updated_at": "2026-02-01T10:38:00Z"
  }
}

POST/api/v1/social/generate

Generate social content from a source URL for one or more platforms. Costs 0.6 credits per platform and requires write permission. Returns a single content_id covering every requested platform, not one per platform.

Request body

Name	Type	Required	Description
source_url	string (URL)	Required	Source page to generate content from
platforms	string[]	Required	Target platforms, 1 to 10 values from the supported list
source_type	string	Optional	website, blog, or youtube Default website.
angle	string	Optional	Direction hint for the post, for example "focus on the cost savings" (max 500 characters)
title	string	Optional	Override the derived title (max 200 characters)
project_id	uuid	Optional	Project to generate under. Defaults to your active project.

Request

curl -X POST https://www.brainpercent.app/api/v1/social/generate \
  -H "Authorization: Bearer bp_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "source_url": "https://example.com/blog/ai-seo-strategies",
    "platforms": ["twitter", "linkedin"],
    "source_type": "blog",
    "angle": "Lead with the measurable result, not the tooling"
  }'

202Response

{
  "success": true,
  "data": {
    "content_id": "c4a1e8b2-9f3d-4e7a-b5c6-1d2e3f4a5b6c",
    "status": "generating",
    "platforms": [
      "twitter",
      "linkedin"
    ],
    "credits_deducted": 1.2,
    "credits_remaining": 58.8,
    "poll_url": "/api/v1/social/content/c4a1e8b2-9f3d-4e7a-b5c6-1d2e3f4a5b6c"
  }
}

POST/api/v1/social/publish

Publish or schedule a social content record to your connected accounts. Omit scheduled_at to publish immediately. Requires write permission and at least one connected social profile.

Request body

Name	Type	Required	Description
content_id	uuid	Required	ID of the social content record to publish
platforms	string[]	Optional	Optional subset of platforms to publish. Defaults to every platform present on the record.
scheduled_at	datetime	Optional	ISO 8601 timestamp to schedule publishing. Omit to publish now.

Request

# Publish now, to every platform on the record
curl -X POST https://www.brainpercent.app/api/v1/social/publish \
  -H "Authorization: Bearer bp_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "content_id": "c4a1e8b2-9f3d-4e7a-b5c6-1d2e3f4a5b6c" }'

# Or schedule a subset of platforms
curl -X POST https://www.brainpercent.app/api/v1/social/publish \
  -H "Authorization: Bearer bp_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content_id": "c4a1e8b2-9f3d-4e7a-b5c6-1d2e3f4a5b6c",
    "platforms": ["linkedin"],
    "scheduled_at": "2026-02-15T14:00:00Z"
  }'

202Response

{
  "success": true,
  "data": {
    "content_id": "c4a1e8b2-9f3d-4e7a-b5c6-1d2e3f4a5b6c",
    "status": "publishing",
    "profiles": 2
  }
}

Data model

One post, many variants. platforms changes shape when the job finishes. Images live on image_urls[platform] — permanent Storage URLs.

When	Shape	Example
Still generating	Array of names	["linkedin", "instagram"]
Finished	Object of captions	{ "linkedin": "caption…" }

Statuses

Status
draft
queued
generating
ready
completed
scheduled
published
failed

Platforms

These 13 live values are accepted in the platforms array and the platform filter.

Platform	Value
Instagram	instagram
Facebook	facebook
LinkedIn	linkedin
Twitter / X	twitter
Threads	threads
TikTok	tiktok
YouTube	youtube
Pinterest	pinterest
Bluesky	bluesky
Telegram	telegram
Google Business	google-business
Reddit	reddit
Snapchat	snapchat

Permissions and credits

Endpoint	Permission	Scope	Credits
GET /social/content	read	social	0
GET /social/content/:id	read	social	0
POST /social/generate	write	social	0.6 per platform
POST /social/publish	write	social	0

Errors

Status	Code	When
400	VALIDATION_ERROR	Missing source_url, empty platforms, unknown platform
400	NO_PROJECT	No project on the account
402	INSUFFICIENT_CREDITS	Wallet cannot cover the platforms
403	FORBIDDEN	Missing write or social scope
404	NOT_FOUND	content_id missing or not yours
409	CONFLICT	Already published
412	PRECONDITION_FAILED	Still generating, or no connected channel

Connect channels at social accounts before publish.

Scheduling

Request	HTTP	Returned status
Omit scheduled_at	202	publishing
Send scheduled_at	200	scheduled

ISO 8601. UTC is the usual form. An offset such as 2026-02-15T09:00:00-05:00 is accepted.

200Scheduled

{
  "success": true,
  "data": {
    "content_id": "c4a1e8b2-9f3d-4e7a-b5c6-1d2e3f4a5b6c",
    "status": "scheduled",
    "scheduled_at": "2026-02-15T14:00:00Z"
  }
}