Social Media Assistant (via post-bridge.com)

Autonomously manage social media posting via Post Bridge API.

Setup

1. Create a Post Bridge account at post-bridge.com
2. Connect your social accounts (TikTok, Instagram, YouTube, Twitter, etc.)
3. Enable API access (Settings → API)
4. Store your API key in workspace .env:

   POST_BRIDGE_API_KEY=pb_live_xxxxx
   

5. Download API docs: https://api.post-bridge.com/reference → save to workspace as post-bridge-api.json

Auth

All requests use Bearer token:

Authorization: Bearer <POST_BRIDGE_API_KEY>

Base URL: https://api.post-bridge.com

Core Workflow

1. Get Social Accounts

GET /v1/social-accounts

Returns array of connected accounts with id, platform, username. Store these IDs — you need them for every post.

2. Upload Media

POST /v1/media/create-upload-url
Body: { "mime_type": "video/mp4", "size_bytes": <int>, "name": "video.mp4" }

Returns media_id + upload_url. Then:

PUT <upload_url>
Content-Type: video/mp4
Body: <binary file>

3. Create Post

POST /v1/posts
Body: {
  "caption": "your caption here #hashtags",
  "media": ["<media_id>"],
  "social_accounts": [<account_id_1>, <account_id_2>],
  "scheduled_at": "2026-01-01T14:00:00Z",  // omit for instant post
  "platform_configurations": { ... }  // optional, see below
}

Additional create options:

• media_urls: Array of publicly accessible URLs (used instead of media if no media IDs). Example: ["https://example.com/video.mp4"]
• is_draft: If true, creates the post but does not process it until updated with a scheduled date or posted instantly later.
• processing_enabled: If false, skips video processing. Defaults to true.
• use_queue: Automatically schedule to your next available queue slot (configured in the Post Bridge dashboard). Cannot be used with scheduled_at. Pass true to use your saved timezone, or { "timezone": "America/New_York" } to override.

use_queue example:

{
  "caption": "Queued post!",
  "media": ["<media_id>"],
  "social_accounts": [44029],
  "use_queue": true
}

This finds the next open slot in your queue schedule and sets scheduled_at automatically. You must have a queue schedule configured in the dashboard first.

4. Update or Delete Scheduled Posts

PATCH /v1/posts/<post_id>

Update a scheduled post (caption, schedule time, etc.). Only works on posts with scheduled status.

DELETE /v1/posts/<post_id>

Delete a scheduled post. Only works on posts with scheduled status.

5. Check Results

GET /v1/posts/<post_id>

Returns status: processing, scheduled, posted, failed.

GET /v1/post-results

List all post results across platforms (paginated with offset and limit).

6. Analytics

GET /v1/analytics

Retrieve performance data (views, likes, shares, comments, etc.) for posts.

Query parameters:

• platform — filter by platform (e.g. tiktok, youtube, instagram)
• post_result_id[] — filter by specific post result IDs (multiple values = OR logic)
• timeframe — 7d, 30d, 90d, or all (default: all)
• offset / limit — pagination

Returns: view_count, like_count, comment_count, share_count, cover_image_url, share_url, duration, and more per record.

POST /v1/analytics/sync

Manually trigger a sync of analytics from platforms. Optionally pass ?platform=tiktok to sync a specific platform only. Rate-limited to once every 5 minutes.

Platform Configurations

Pass inside platform_configurations object on post creation. Crucial: Always wrap these in the correct platform key to ensure they only apply to the target platform and don't cause issues on other platforms in the same post.

TikTok (tiktok):

• draft: true — save as draft (publish manually on TikTok with trending sound)
• video_cover_timestamp_ms: 3000 — cover thumbnail
• is_aigc: true — label as AI-generated content

Example of correct multi-platform config:

{
  "caption": "Default caption",
  "social_accounts": [44029, 44030],
  "platform_configurations": {
    "tiktok": {
      "draft": true,
      "is_aigc": false
    },
    "instagram": {
      "is_trial_reel": false
    }
  }
}

Instagram (instagram):

• video_cover_timestamp_ms: 3000 — cover thumbnail
• is_trial_reel: true — trial reel mode (needs 1000+ followers)
• trial_graduation: "SS_PERFORMANCE" — auto-graduate based on performance

YouTube:

• video_cover_timestamp_ms: 3000 — cover thumbnail
• title: "My Short Title" — override post title

Twitter/X:

• caption: "override caption" — platform-specific caption

All platforms support caption and media overrides for per-platform customization.

Recommended Workflow for Video Content

1. Store videos in a local folder
2. Extract a frame with ffmpeg to read any text overlays:

   ffmpeg -i video.mp4 -ss 00:00:04 -frames:v 1 frame.jpg -y
   

3. Write caption based on video content + hashtags
4. Upload → create post → schedule or post instantly (or use use_queue to auto-schedule)
5. Move posted videos to a posted/ subfolder to avoid duplicates
6. Set a cron to check post status 5 mins after scheduled time
7. Track performance with GET /v1/analytics or by browsing platform pages

Tips

• Post to multiple platforms simultaneously by including multiple account IDs
• Stagger posts throughout the day (e.g. 9am + 3pm) for better reach
• Use scheduled_at to pre-schedule batches — Post Bridge handles the timing
• Use use_queue to auto-fill your queue schedule without calculating times yourself
• TikTok draft mode lets you add trending sounds manually before publishing
• Keep hashtags to 4-5 per post for best engagement
• Monitor what works and iterate on captions/formats