Posbly API Documentation

Overview

Posbly is an API-first social media broadcasting service for automation builders, AI agents, and developers. Publish to 9 platforms simultaneously from one request.

Authentication

All protected endpoints require a pk_... API key as a Bearer token. Generate and manage your keys from the dashboard.

Authorization: Bearer pk_your_api_key_here

curl -H "Authorization: Bearer pk_abc123" \
  https://api.posbly.com/v1/broadcast

Account

{
  "id": "uuid-here",
  "email": "user@example.com",
  "name": "Jane Doe"
}

Platform Connections

Manage OAuth tokens for each social platform. Connect accounts via the OAuth flow, then use the connection ID when broadcasting.

{
  "id": "uuid",
  "platform": "INSTAGRAM",
  "platform_user_id": "123456",
  "display_name": "@janedoe",
  "username": "janedoe",
  "created_at": "2026-03-13T00:00:00Z",
  "token_expires_at": "2026-06-13T00:00:00Z",
  "metadata": {}
}

Broadcasts

The core endpoint. Publish content to one or more platforms in a single API call. Returns 202 Accepted immediately — jobs run asynchronously.

{
  "platforms": {                          // object, not an array
    "instagram": ["@brand_account"],      // slug → array of account names
    "x": ["@myhandle"],
    "linkedin": ["@My Company Page"]      // can include multiple accounts per platform
  },
  "content": {
    "text": "Hello from Posbly! 🚀",
    "media_url": "https://example.com/your-image.jpg",             // optional, any public URL
    "media_type": "image",                // "image" or "video" — required if media_url set
    "carousel_items": [                   // optional, Instagram only (2–10 items)
      { "media_url": "https://...", "media_type": "image" },
      { "media_url": "https://...", "media_type": "image" }
    ],
    "link": "https://example.com"         // optional, Facebook only
  },
  "schedule_at": "2026-04-01T09:00:00Z", // optional, ISO 8601, up to 30 days out
  "clientReferenceId": "run-abc-123",     // optional, idempotency key (24h TTL)
  "metadata": { "campaign": "spring" }   // optional, echoed in webhooks
}

{
  "broadcast_id": "brd_...",
  "status": "PENDING",
  "idempotent": false,
  "scheduled_for": null,
  "created_at": "2026-03-13T12:00:00Z",
  "metadata": { "campaign": "spring" },
  "jobs": [
    { "job_id": "job_...", "platform": "INSTAGRAM", "status": "QUEUED", "connection_id": "uuid" },
    { "job_id": "job_...", "platform": "X",         "status": "QUEUED", "connection_id": "uuid" },
    { "job_id": "job_...", "platform": "LINKEDIN",  "status": "QUEUED", "connection_id": "uuid" }
  ]
}

Jobs

Each platform post is a separate Job within a Broadcast. Poll for per-platform results.

{
  "job_id": "job_...",
  "platform": "X",
  "status": "COMPLETED",
  "post_url": "https://x.com/user/status/1234",
  "external_post_id": "1234567890",
  "published_at": "2026-03-13T12:01:00Z",
  "completed_at": "2026-03-13T12:01:05Z",
  "attempts": 1,
  "error_code": null,
  "error_message": null
}

Webhooks

Register a webhook URL to receive real-time event notifications. All payloads are signed with HMAC-SHA256.

{
  "url": "https://your-server.com/webhooks/posbly",
  "events": ["JOB_COMPLETED", "JOB_FAILED", "BROADCAST_COMPLETED", "BROADCAST_FAILED"]
}

// Response
{
  "id": "uuid",
  "url": "https://your-server.com/webhooks/posbly",
  "events": ["JOB_COMPLETED", "JOB_FAILED"],
  "secret": "whsec_abc123...",  // shown once — store securely
  "created_at": "2026-03-13T00:00:00Z"
}

// Signature verification
const signature = req.headers['x-posbly-signature'];
// Format: sha256=<hex-digest>

const expected = 'sha256=' + crypto
  .createHmac('sha256', WEBHOOK_SECRET)
  .update(JSON.stringify(payload))
  .digest('hex');

if (signature !== expected) throw new Error('Invalid signature');

Billing & Credits

Posbly uses a credit-based system. Each broadcast job consumes credits. Top up via Stripe.

// POST /v1/billing/checkout
{ "amount": 5000 }  // in cents ($50.00)

// Response
{ "url": "https://checkout.stripe.com/..." }

User Settings

{ "timezone": "America/New_York" }

OAuth Flows

Connect social media accounts via OAuth. Redirect users to the connect URL, then handle the callback.

https://api.posbly.com/v1/oauth/:platform/connect?token=<session_token>

X:         https://api.posbly.com/v1/oauth/x/callback
Meta/FB:   https://api.posbly.com/v1/oauth/meta/callback
Instagram: https://api.posbly.com/v1/oauth/instagram/callback
Pinterest: https://api.posbly.com/v1/oauth/pinterest/callback
Threads:   https://api.posbly.com/v1/oauth/threads/callback
LinkedIn:  https://api.posbly.com/v1/oauth/linkedin/callback
YouTube:   https://api.posbly.com/v1/oauth/youtube/callback
TikTok:    https://api.posbly.com/v1/oauth/tiktok/callback

Error Handling

All errors return a consistent JSON structure.

{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "Authorization header with Bearer token is required"
  }
}

Rate Limiting

Rate limits are enforced per API key. Exceeding limits returns 429 Too Many Requests.

Facebook Pages

Manage your Facebook Page content beyond broadcasting — list posts, read and reply to comments, view page and post-level insights.

Posts & Comments

// POST /v1/connections/:id/posts/:postId/comments
{
  "message": "Thanks for the feedback!"
}

// Response (201 Created)
{
  "commentId": "123456789_987654321"
}

Insights & Analytics

GET /v1/connections/:id/insights?period=week&since=2026-03-01&until=2026-03-25

// period: day | week | days_28 | month (default: week)
// Metrics: page_impressions, page_engaged_users, page_fans,
//          page_views_total, page_post_engagements

Platform Guides

Key requirements and limits for each platform.