post-bridge

name	post-bridge
description	Interact with the Post Bridge social media post management API. Use when the user wants to publish posts, upload media, manage social accounts, schedule content, or retrieve analytics via the Post Bridge platform. Triggers on: post to instagram, upload media to post bridge, schedule a social post, list social accounts, create a post, publish video, post bridge api.

Post Bridge API

Manage social media posts across connected accounts using the Post Bridge API. Authentication uses the POST_BRIDGE_API_KEY environment variable.

---

Authentication

All requests require a Bearer token header. Verify the key is set before making calls:

echo "Key set: ${POST_BRIDGE_API_KEY:+yes}"

Use this header on every request:

Authorization: Bearer $POST_BRIDGE_API_KEY

---

Core Workflow

Publishing a post follows four steps. Execute them in order — each step depends on the previous.

Step 1: Retrieve Social Accounts

Identify which account(s) to publish to. Capture the account id values (these are numbers) for use in post creation.

curl -s -H "Authorization: Bearer $POST_BRIDGE_API_KEY" \
  "https://api.post-bridge.com/v1/social-accounts" | jq .

Filter by platform if needed:

curl -s -H "Authorization: Bearer $POST_BRIDGE_API_KEY" \
  "https://api.post-bridge.com/v1/social-accounts?platform=instagram" | jq .

Step 2: Generate Upload URL (media posts only)

Skip this step for text-only posts. Also skip if using media_urls (publicly accessible URLs) instead of uploading files directly.

Request a signed upload URL for each media file. Note the upload_url and media_id from the response.

FILE_SIZE=$(stat -c%s "photo.jpg")
UPLOAD_RESPONSE=$(curl -s -X POST \
  -H "Authorization: Bearer $POST_BRIDGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"name\": \"photo.jpg\", \"mime_type\": \"image/jpeg\", \"size_bytes\": $FILE_SIZE}" \
  "https://api.post-bridge.com/v1/media/create-upload-url")

UPLOAD_URL=$(echo "$UPLOAD_RESPONSE" | jq -r '.upload_url')
MEDIA_ID=$(echo "$UPLOAD_RESPONSE" | jq -r '.media_id')
echo "Media ID: $MEDIA_ID"

Step 3: Upload File to Signed URL

PUT the file directly to the signed URL. No authorization header is needed for this request.

curl -s -X PUT \
  -H "Content-Type: image/jpeg" \
  --data-binary @photo.jpg \
  "$UPLOAD_URL"

Upload promptly — the signed URL expires after a short window. Unused media auto-deletes after 24 hours.

Step 4: Create Post

Combine the account ID(s) and media ID(s) to create the post. Account IDs are numbers.

curl -s -X POST \
  -H "Authorization: Bearer $POST_BRIDGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"social_accounts\": [$ACCOUNT_ID],
    \"caption\": \"Your caption here\",
    \"media\": [\"$MEDIA_ID\"]
  }" \
  "https://api.post-bridge.com/v1/posts" | jq .

Alternative — use media_urls instead of uploading:

curl -s -X POST \
  -H "Authorization: Bearer $POST_BRIDGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"social_accounts\": [$ACCOUNT_ID],
    \"caption\": \"Your caption here\",
    \"media_urls\": [\"https://example.com/photo.jpg\"]
  }" \
  "https://api.post-bridge.com/v1/posts" | jq .

media_urls accepts publicly accessible URLs. Ignored if media is also provided.

---

Scheduling Options

Immediate posting: Omit both scheduled_at and use_queue.

Specific time:

{ "scheduled_at": "2026-03-10T14:00:00Z" }

Auto-queue (next available slot):

{ "use_queue": { "timezone": "America/New_York" } }

scheduled_at and use_queue cannot be used together.

---

Draft Mode

Save a post without publishing or scheduling:

{ "is_draft": true }

---

Platform Configurations

Override caption, media, or platform-specific settings per platform:

{
  "platform_configurations": {
    "linkedin": { "caption": "LinkedIn-specific text", "media": ["med_1"] },
    "instagram": {
      "caption": "IG caption",
      "media": ["med_2"],
      "cover_image": "med_cover",
      "video_cover_timestamp_ms": 5000,
      "placement": "reels",
      "is_trial_reel": false
    },
    "tiktok": {
      "caption": "TikTok caption",
      "media": ["med_3"],
      "title": "Video title",
      "draft": false,
      "is_aigc": false
    },
    "youtube": { "caption": "Description", "media": ["med_4"], "title": "Video title" },
    "pinterest": {
      "caption": "Pin description",
      "media": ["med_5"],
      "board_ids": ["board_1"],
      "link": "https://example.com",
      "title": "Pin title"
    },
    "facebook": { "caption": "FB text", "media": ["med_6"], "placement": "reels" },
    "twitter": { "caption": "Tweet text", "media": ["med_7"] },
    "bluesky": { "caption": "Bluesky text", "media": ["med_8"] },
    "threads": { "caption": "Threads text", "media": ["med_9"], "location": "reels" }
  }
}

---

Account Configurations

Override caption/media per social account in multi-account posts:

{
  "account_configurations": {
    "account_configurations": [
      { "account_id": 42, "caption": "Custom text for this account", "media": ["med_1"] }
    ]
  }
}

---

Examples

Example 1: Publish an Image to Instagram Now

User: "Post this photo to my Instagram with the caption 'New arrivals just dropped.'"

# Step 1 - find the instagram account
ACCOUNT=$(curl -s -H "Authorization: Bearer $POST_BRIDGE_API_KEY" \
  "https://api.post-bridge.com/v1/social-accounts?platform=instagram" | jq -r '.data[0].id')

# Step 2 - get upload URL
FILE_SIZE=$(stat -c%s "arrivals.jpg")
UPLOAD_RESP=$(curl -s -X POST \
  -H "Authorization: Bearer $POST_BRIDGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"name\": \"arrivals.jpg\", \"mime_type\": \"image/jpeg\", \"size_bytes\": $FILE_SIZE}" \
  "https://api.post-bridge.com/v1/media/create-upload-url")
UPLOAD_URL=$(echo "$UPLOAD_RESP" | jq -r '.upload_url')
MEDIA_ID=$(echo "$UPLOAD_RESP" | jq -r '.media_id')

# Step 3 - upload file
curl -s -X PUT -H "Content-Type: image/jpeg" \
  --data-binary @arrivals.jpg "$UPLOAD_URL"

# Step 4 - create post (no scheduled_at = publish immediately)
curl -s -X POST \
  -H "Authorization: Bearer $POST_BRIDGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"social_accounts\": [$ACCOUNT],
    \"caption\": \"New arrivals just dropped.\",
    \"media\": [\"$MEDIA_ID\"]
  }" \
  "https://api.post-bridge.com/v1/posts" | jq .

Example 2: Post with a Public Image URL (no upload needed)

User: "Post this image to LinkedIn: https://example.com/banner.png"

ACCOUNT=$(curl -s -H "Authorization: Bearer $POST_BRIDGE_API_KEY" \
  "https://api.post-bridge.com/v1/social-accounts?platform=linkedin" | jq -r '.data[0].id')

curl -s -X POST \
  -H "Authorization: Bearer $POST_BRIDGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"social_accounts\": [$ACCOUNT],
    \"caption\": \"Check out our new banner!\",
    \"media_urls\": [\"https://example.com/banner.png\"]
  }" \
  "https://api.post-bridge.com/v1/posts" | jq .

Example 3: Schedule a Video Reel with Custom Cover

User: "Schedule this reel for Friday at 9am EST with a custom thumbnail."

# Step 1 - get account
ACCOUNT=$(curl -s -H "Authorization: Bearer $POST_BRIDGE_API_KEY" \
  "https://api.post-bridge.com/v1/social-accounts?platform=instagram" | jq -r '.data[0].id')

# Step 2+3 - upload reel video
REEL_SIZE=$(stat -c%s "reel.mp4")
REEL_RESP=$(curl -s -X POST \
  -H "Authorization: Bearer $POST_BRIDGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"name\": \"reel.mp4\", \"mime_type\": \"video/mp4\", \"size_bytes\": $REEL_SIZE}" \
  "https://api.post-bridge.com/v1/media/create-upload-url")
REEL_URL=$(echo "$REEL_RESP" | jq -r '.upload_url')
REEL_ID=$(echo "$REEL_RESP" | jq -r '.media_id')
curl -s -X PUT -H "Content-Type: video/mp4" --data-binary @reel.mp4 "$REEL_URL"

# Step 2+3 - upload cover image
COVER_SIZE=$(stat -c%s "cover.jpg")
COVER_RESP=$(curl -s -X POST \
  -H "Authorization: Bearer $POST_BRIDGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"name\": \"cover.jpg\", \"mime_type\": \"image/jpeg\", \"size_bytes\": $COVER_SIZE}" \
  "https://api.post-bridge.com/v1/media/create-upload-url")
COVER_URL=$(echo "$COVER_RESP" | jq -r '.upload_url')
COVER_ID=$(echo "$COVER_RESP" | jq -r '.media_id')
curl -s -X PUT -H "Content-Type: image/jpeg" --data-binary @cover.jpg "$COVER_URL"

# Step 4 - create scheduled post with cover image
curl -s -X POST \
  -H "Authorization: Bearer $POST_BRIDGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"social_accounts\": [$ACCOUNT],
    \"caption\": \"Check this out!\",
    \"media\": [\"$REEL_ID\"],
    \"scheduled_at\": \"2026-03-06T14:00:00Z\",
    \"platform_configurations\": {
      \"instagram\": {
        \"cover_image\": \"$COVER_ID\"
      }
    }
  }" \
  "https://api.post-bridge.com/v1/posts" | jq .

Example 4: List and Update a Scheduled Post

User: "Show me my scheduled posts and push the next one back by a day."

# List scheduled posts
curl -s -H "Authorization: Bearer $POST_BRIDGE_API_KEY" \
  "https://api.post-bridge.com/v1/posts?status=scheduled" | jq .

# Update the scheduled time (always include scheduled_at to prevent immediate processing)
curl -s -X PATCH \
  -H "Authorization: Bearer $POST_BRIDGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scheduled_at": "2026-03-11T14:00:00Z"}' \
  "https://api.post-bridge.com/v1/posts/post_def456" | jq .

Example 5: Check Analytics

User: "Pull the latest analytics for my posts."

# Sync first to get fresh data (optionally filter by platform)
curl -s -X POST -H "Authorization: Bearer $POST_BRIDGE_API_KEY" \
  "https://api.post-bridge.com/v1/analytics/sync" | jq .

# Retrieve analytics (with optional timeframe filter)
curl -s -H "Authorization: Bearer $POST_BRIDGE_API_KEY" \
  "https://api.post-bridge.com/v1/analytics?timeframe=30d" | jq .

# Check post-level publish results
curl -s -H "Authorization: Bearer $POST_BRIDGE_API_KEY" \
  "https://api.post-bridge.com/v1/post-results" | jq .

Example 6: Verify a Post Was Published Successfully

POST_ID="post_abc123"
curl -s -H "Authorization: Bearer $POST_BRIDGE_API_KEY" \
  "https://api.post-bridge.com/v1/post-results?post_id=$POST_ID" | jq .
# Check .data[].success and .data[].platform_data.url for the live post link

---

Guidelines

• Always verify POST_BRIDGE_API_KEY is set before making API calls.
• Complete media uploads promptly after generating the signed URL — it expires quickly.
• Reference the full endpoint list and request/response shapes in references/api-endpoints.md.
• Use jq . to pretty-print JSON responses; adapt field access (.data[0].id) to actual response shape.
• When the user does not specify a time, ask whether they want immediate posting, a specific time, or queue scheduling.
• For multi-platform posts, include all target account IDs in the social_accounts array in a single post creation call.
• Use media_urls when the user provides public image/video URLs — avoids the upload flow.
• After publishing, check post results via GET /v1/post-results?post_id=X to confirm success.
• On 429 errors, wait before retrying. On 500 errors, retry once after a brief delay.