Social Media

Generate and publish social media content across platforms.

GET/api/v1/social/content

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

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 by platform: twitter, linkedin, facebook, instagram
status	string	Optional	Filter by status: draft, published, scheduled, failed
article_id	uuid	Optional	Filter by source article ID

Request

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

200Response

{
  "success": true,
  "data": [
    {
      "id": "c4a1e8b2-9f3d-4e7a-b5c6-1d2e3f4a5b6c",
      "platform": "twitter",
      "content": "Check out our latest article on AI SEO strategies for 2026! Key takeaways inside. #SEO #AI",
      "status": "draft",
      "article_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "created_at": "2026-02-01T10:30:00Z",
      "updated_at": "2026-02-01T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 15,
    "page": 1,
    "limit": 10,
    "total_pages": 2,
    "has_more": true
  }
}

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

Returns full details for a single social content item, including the generated text, platform metadata, and publishing history.

Request

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

200Response

{
  "success": true,
  "data": {
    "id": "c4a1e8b2-9f3d-4e7a-b5c6-1d2e3f4a5b6c",
    "platform": "twitter",
    "content": "Check out our latest article on AI SEO strategies for 2026! Key takeaways inside. #SEO #AI",
    "status": "draft",
    "article_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "scheduled_at": null,
    "published_at": null,
    "platform_post_id": null,
    "created_at": "2026-02-01T10:30:00Z",
    "updated_at": "2026-02-01T10:30:00Z"
  }
}

POST/api/v1/social/generate

Generate social media content from a source URL for one or more platforms. Costs 9 credits per platform. Requires write permission.

Request Body

Name	Type	Required	Description
source_url	string (URL)	Required	Source article or blog post URL to generate content from
platforms	string[]	Required	Target platforms: twitter, linkedin, facebook, instagram
tone	string	Optional	Writing tone: professional, casual, humorous, informative(default: `professional`)
language	string	Optional	Language code (ISO 639-1)(default: `en`)

Request

curl -X POST https://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"],
    "tone": "professional"
  }'

202Response

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "d5b2f9c3-a0e4-5f8b-c6d7-2e3f4a5b6c7d",
        "platform": "twitter",
        "status": "generating"
      },
      {
        "id": "e6c3a0d4-b1f5-6a9c-d7e8-3f4a5b6c7d8e",
        "platform": "linkedin",
        "status": "generating"
      }
    ],
    "status": "generating",
    "credits_charged": 18
  }
}

POST/api/v1/social/publish

Publish or schedule social content to a connected platform account. Requires an active platform connection and write permission.

Request Body

Name	Type	Required	Description
content_id	uuid	Required	ID of the social content item to publish
platform	string	Required	Target platform: twitter, linkedin, facebook, instagram
scheduled_at	datetime	Optional	ISO 8601 timestamp to schedule publishing. Omit for immediate publish.

Request

curl -X POST https://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",
    "platform": "twitter",
    "scheduled_at": "2026-02-15T14:00:00Z"
  }'

202Response

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

Supported Platforms

Platform	Value	Character Limit	Features
Twitter / X	`twitter`	280 characters	Hashtags, mentions, threads
LinkedIn	`linkedin`	3,000 characters	Professional formatting, hashtags
Facebook	`facebook`	63,206 characters	Rich text, links, hashtags
Instagram	`instagram`	2,200 characters	Hashtags, caption optimization

Permissions & Credits

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

Credit calculation: Generating social content costs 9 credits multiplied by the number of platforms. For example, generating for Twitter + LinkedIn costs 18 credits (9 × 2). Generating for all 4 platforms costs 36 credits (9 × 4).

Error Responses

Status	Code	When
402	`INSUFFICIENT_CREDITS`	Balance below cost for requested platforms
409	`CONFLICT`	Attempting to publish already-published content
412	`PRECONDITION_FAILED`	Platform account not connected (connect in dashboard settings)

Scheduling Content

Use the scheduled_at parameter in the publish endpoint to schedule content for future publication. The value must be an ISO 8601 datetime string in UTC.

Format	Example	Notes
ISO 8601 UTC	2026-02-15T14:00:00Z	Recommended format
With timezone offset	2026-02-15T09:00:00-05:00	Converted to UTC on server

Scheduled times must be at least 5 minutes in the future. Past dates will return a 400 VALIDATION_ERROR.