Authenticated API

This endpoint requires a valid JWT Bearer token with content_creator roles. Accessible via the API gateway.

Social Publishing API

Multi-platform social media publishing, scheduling, and distribution for the Creator Revolution platform.

Overview

Attribute	Value
Base Path	`/api/v1/creator/social`
Authentication	Bearer Token
Required Roles	`creator`, `content_manager`, `manager`, `tenant_admin`, `platform_admin`, `system_admin`, `super_admin`

Supported Platforms

Platform	Post Types	Features
Twitter/X	Text, Images, Video, Threads	Scheduling, Analytics
LinkedIn	Text, Images, Video, Articles	Scheduling, Analytics
Instagram	Images, Video, Reels, Stories	Scheduling, Analytics
YouTube	Video, Shorts, Community	Scheduling, Analytics
TikTok	Video	Scheduling, Analytics
Facebook	Text, Images, Video	Scheduling, Analytics

Publishing

Publish Content

Publish content to one or more social platforms.

POST /api/v1/creator/social/publish

Request Body

{
  "content": {
    "text": "Excited to announce our new AI-powered features! 🚀\n\nCheck out what's new in the latest update.",
    "media": [
      {
        "type": "image",
        "url": "https://cdn.example.com/images/announcement.png",
        "alt_text": "New features announcement graphic"
      }
    ],
    "link": {
      "url": "https://example.com/blog/new-features",
      "title": "New AI Features",
      "description": "Discover our latest innovations"
    }
  },
  "platforms": [
    {
      "platform": "twitter",
      "account_id": "acc_twitter_001",
      "options": {
        "reply_settings": "everyone"
      }
    },
    {
      "platform": "linkedin",
      "account_id": "acc_linkedin_001",
      "options": {
        "visibility": "public"
      }
    }
  ],
  "publish_at": "2026-01-24T20:00:00Z"
}

Response

{
  "publish_id": "pub_001",
  "status": "scheduled",
  "scheduled_for": "2026-01-24T20:00:00Z",
  "platforms": [
    {
      "platform": "twitter",
      "account_id": "acc_twitter_001",
      "status": "scheduled",
      "estimated_reach": 15000
    },
    {
      "platform": "linkedin",
      "account_id": "acc_linkedin_001",
      "status": "scheduled",
      "estimated_reach": 8500
    }
  ],
  "created_at": "2026-01-24T19:30:00Z"
}

Create Post

Create a social post for later publishing.

POST /api/v1/creator/social/posts

Request Body

{
  "title": "Product Launch Announcement",
  "content": {
    "text": "Big news coming tomorrow! Stay tuned for our major product launch.",
    "hashtags": ["launch", "innovation", "tech"],
    "mentions": ["@partner_company"]
  },
  "media": [],
  "platforms": ["twitter", "linkedin", "instagram"],
  "status": "draft",
  "campaign_id": "campaign_001",
  "tags": ["product_launch", "q1_2026"]
}

Response

{
  "id": "post_001",
  "title": "Product Launch Announcement",
  "content": {...},
  "platforms": ["twitter", "linkedin", "instagram"],
  "status": "draft",
  "campaign_id": "campaign_001",
  "created_at": "2026-01-24T19:30:00Z",
  "created_by": "user_001"
}

Post Status Values

Status	Description
`draft`	Post created, not scheduled
`scheduled`	Scheduled for future publish
`publishing`	Currently being published
`published`	Successfully published
`failed`	Publishing failed
`cancelled`	Cancelled before publish

Get Post

GET /api/v1/creator/social/posts/{post_id}

Response

{
  "id": "post_001",
  "title": "Product Launch Announcement",
  "content": {
    "text": "Big news coming tomorrow!",
    "hashtags": ["launch", "innovation"],
    "mentions": ["@partner_company"]
  },
  "media": [],
  "platforms": ["twitter", "linkedin", "instagram"],
  "status": "published",
  "published_at": "2026-01-24T20:00:00Z",
  "platform_posts": [
    {
      "platform": "twitter",
      "post_id": "1234567890",
      "url": "https://twitter.com/user/status/1234567890",
      "status": "published"
    },
    {
      "platform": "linkedin",
      "post_id": "urn:li:share:7890",
      "url": "https://linkedin.com/posts/...",
      "status": "published"
    }
  ],
  "analytics": {
    "total_impressions": 25000,
    "total_engagements": 450,
    "engagement_rate": 1.8
  }
}

Update Post

PUT /api/v1/creator/social/posts/{post_id}

Request Body

{
  "content": {
    "text": "Updated announcement text!"
  },
  "platforms": ["twitter", "linkedin"]
}

Delete Post

DELETE /api/v1/creator/social/posts/{post_id}

Publish Post

Publish an existing draft post.

POST /api/v1/creator/social/posts/{post_id}/publish

Request Body

{
  "publish_now": true
}

Schedule Post

Schedule a post for future publishing.

POST /api/v1/creator/social/posts/{post_id}/schedule

Request Body

{
  "scheduled_at": "2026-01-25T14:00:00Z",
  "timezone": "America/Los_Angeles"
}

Cancel Scheduled Post

POST /api/v1/creator/social/posts/{post_id}/cancel

Threads & Series

Create Thread

Create a multi-part thread (Twitter/X).

POST /api/v1/creator/social/threads

Request Body

{
  "platform": "twitter",
  "account_id": "acc_twitter_001",
  "posts": [
    {
      "text": "🧵 Here's everything you need to know about our new AI features (thread):"
    },
    {
      "text": "1/ First, we've added intelligent order prediction that learns from your customers' habits...",
      "media": [{"type": "image", "url": "https://..."}]
    },
    {
      "text": "2/ Next, our voice AI can now handle complex modifications and allergen questions...",
      "media": [{"type": "image", "url": "https://..."}]
    },
    {
      "text": "3/ Finally, the new analytics dashboard gives you real-time insights...\n\nTry it today! Link in bio 👇"
    }
  ],
  "schedule_at": "2026-01-25T10:00:00Z"
}

Response

{
  "thread_id": "thread_001",
  "platform": "twitter",
  "post_count": 4,
  "status": "scheduled",
  "scheduled_at": "2026-01-25T10:00:00Z"
}

Media Management

Upload Media

POST /api/v1/creator/social/media/upload

Request (multipart/form-data)

file: announcement.png
platform_hints: ["twitter", "linkedin", "instagram"]
alt_text: "Product announcement graphic"

Response

{
  "media_id": "media_001",
  "type": "image",
  "url": "https://cdn.example.com/media/media_001.png",
  "thumbnails": {
    "small": "https://cdn.example.com/media/media_001_sm.png",
    "medium": "https://cdn.example.com/media/media_001_md.png"
  },
  "dimensions": {
    "width": 1200,
    "height": 628
  },
  "platform_compatibility": {
    "twitter": {"compatible": true, "optimized": true},
    "linkedin": {"compatible": true, "optimized": true},
    "instagram": {"compatible": false, "reason": "Aspect ratio not supported", "suggestion": "Crop to 1:1 or 4:5"}
  }
}

Get Media

GET /api/v1/creator/social/media/{media_id}

Delete Media

DELETE /api/v1/creator/social/media/{media_id}

Connected Accounts

List Connected Accounts

GET /api/v1/creator/social/accounts

Response

{
  "accounts": [
    {
      "id": "acc_twitter_001",
      "platform": "twitter",
      "username": "@mycompany",
      "display_name": "My Company",
      "profile_image": "https://...",
      "followers": 15420,
      "status": "connected",
      "connected_at": "2025-06-01T00:00:00Z",
      "permissions": ["post", "read_analytics"]
    },
    {
      "id": "acc_linkedin_001",
      "platform": "linkedin",
      "username": "my-company",
      "display_name": "My Company",
      "followers": 8500,
      "status": "connected",
      "account_type": "company_page"
    }
  ]
}

Connect Account

POST /api/v1/creator/social/accounts/connect

Request Body

{
  "platform": "instagram",
  "redirect_uri": "https://app.example.com/oauth/callback"
}

Response

{
  "authorization_url": "https://api.instagram.com/oauth/authorize?...",
  "state": "state_abc123",
  "expires_in": 300
}

Disconnect Account

DELETE /api/v1/creator/social/accounts/{account_id}

Analytics

Get Post Analytics

GET /api/v1/creator/social/posts/{post_id}/analytics

Response

{
  "post_id": "post_001",
  "total": {
    "impressions": 25000,
    "reach": 18500,
    "engagements": 450,
    "engagement_rate": 1.8,
    "clicks": 125,
    "shares": 45,
    "comments": 32,
    "likes": 248
  },
  "by_platform": [
    {
      "platform": "twitter",
      "impressions": 15000,
      "engagements": 280,
      "engagement_rate": 1.87,
      "retweets": 35,
      "likes": 180,
      "replies": 22
    },
    {
      "platform": "linkedin",
      "impressions": 10000,
      "engagements": 170,
      "engagement_rate": 1.7,
      "reactions": 120,
      "comments": 25,
      "shares": 25
    }
  ],
  "timeseries": [
    {"timestamp": "2026-01-24T20:00:00Z", "impressions": 5000, "engagements": 150},
    {"timestamp": "2026-01-24T21:00:00Z", "impressions": 8000, "engagements": 120}
  ]
}

Get Distribution Metrics

GET /api/v1/creator/social/distribution/metrics

Query Parameters

Parameter	Type	Description
`start_date`	date	Period start
`end_date`	date	Period end
`platform`	string	Filter by platform

Response

{
  "period": {
    "start": "2026-01-01",
    "end": "2026-01-24"
  },
  "summary": {
    "total_posts": 45,
    "total_impressions": 850000,
    "total_engagements": 12500,
    "avg_engagement_rate": 1.47,
    "followers_gained": 2500
  },
  "by_platform": [
    {
      "platform": "twitter",
      "posts": 20,
      "impressions": 450000,
      "engagement_rate": 1.8,
      "followers_gained": 1200,
      "best_performing_post": "post_015"
    },
    {
      "platform": "linkedin",
      "posts": 15,
      "impressions": 250000,
      "engagement_rate": 1.5,
      "followers_gained": 800
    }
  ],
  "top_posts": [
    {
      "id": "post_015",
      "title": "AI Feature Launch",
      "impressions": 45000,
      "engagements": 1200
    }
  ],
  "optimal_posting_times": {
    "twitter": ["09:00", "12:00", "17:00"],
    "linkedin": ["08:00", "12:00", "16:00"]
  }
}

Scheduling

Get Optimal Times

Get AI-recommended optimal posting times.

GET /api/v1/creator/social/scheduling/optimal-times

Query Parameters

Parameter	Type	Description
`platform`	string	Target platform
`content_type`	string	Type of content
`timezone`	string	Target timezone

Response

{
  "platform": "twitter",
  "recommendations": [
    {
      "day": "tuesday",
      "times": [
        {"time": "09:00", "score": 92, "reason": "Peak morning engagement"},
        {"time": "12:30", "score": 88, "reason": "Lunch break browsing"}
      ]
    },
    {
      "day": "wednesday",
      "times": [
        {"time": "10:00", "score": 90},
        {"time": "15:00", "score": 85}
      ]
    }
  ],
  "avoid": [
    {"day": "sunday", "times": ["06:00-09:00"], "reason": "Low engagement"}
  ]
}

Get Queue

GET /api/v1/creator/social/scheduling/queue

Response

{
  "queue": [
    {
      "id": "post_002",
      "title": "Weekly Tips",
      "scheduled_at": "2026-01-25T10:00:00Z",
      "platforms": ["twitter", "linkedin"],
      "status": "scheduled"
    },
    {
      "id": "post_003",
      "title": "Product Update",
      "scheduled_at": "2026-01-26T14:00:00Z",
      "platforms": ["twitter"],
      "status": "scheduled"
    }
  ],
  "total_scheduled": 8
}

Webhooks

Event	Description
`social.post_published`	Post published successfully
`social.post_failed`	Post publishing failed
`social.engagement_spike`	Unusual engagement detected
`social.account_disconnected`	Account auth expired
`social.mention_received`	Brand mention detected

Error Responses

Status	Code	Description
400	`invalid_content`	Content validation failed
400	`media_unsupported`	Media format not supported
401	`account_disconnected`	Platform auth expired
403	`rate_limited`	Platform rate limit reached
404	`post_not_found`	Post ID not found
413	`media_too_large`	Media exceeds size limit

Creator Revolution Guide - Platform overview
Content Management - Content API
Podcast Distribution - Podcast API

Overview​

Supported Platforms​

Publishing​

Publish Content​

Create Post​

Post Status Values​

Get Post​

Update Post​

Delete Post​

Publish Post​

Schedule Post​

Cancel Scheduled Post​

Threads & Series​

Create Thread​

Media Management​

Upload Media​

Get Media​

Delete Media​

Connected Accounts​

List Connected Accounts​

Connect Account​

Disconnect Account​

Analytics​

Get Post Analytics​

Get Distribution Metrics​

Scheduling​

Get Optimal Times​

Get Queue​

Webhooks​

Error Responses​

Related Documentation​

Overview

Supported Platforms

Publishing

Publish Content

Create Post

Post Status Values

Get Post

Update Post

Delete Post

Publish Post

Schedule Post

Cancel Scheduled Post

Threads & Series

Create Thread

Media Management

Upload Media

Get Media

Delete Media

Connected Accounts

List Connected Accounts

Connect Account

Disconnect Account

Analytics

Get Post Analytics

Get Distribution Metrics

Scheduling

Get Optimal Times

Get Queue

Webhooks

Error Responses

Related Documentation