Postgale REST API

Publish, schedule and moderate posts on Reddit, Instagram, Facebook Pages, Threads and TikTok, answer Instagram and Messenger direct messages, and send and receive WhatsApp messages (WhatsApp guide). This page is a concise reference; the machine-readable spec is at /api/v1/openapi.json. AI agents can use the same operations through the MCP server.

Basics

• Base URL: https://postgale.com/api/v1. JSON in, JSON out.
• Authentication: Authorization: Bearer sk_… with a key from Dashboard → API keys. A key acts for its organization only.
• Rate limit: 60 requests per minute per key by default; over the limit answers 429.
• Idempotency: send x-request-id on POST /posts. A retry with the same id returns the original post (200 instead of 201). The same text cannot be posted twice within 24 hours.
• Approval: when the organization, an account or the key requires approval, new posts are held as pending_approval until a person approves them in the dashboard (/posts/{id}/approve and /reject always answer 403 to API keys). While approval applies, comment moderation, published-post changes and sending direct messages are refused with approval_required; reads are never blocked.
• API keys (/keys) and organization settings (/org-settings) are dashboard-session only.

Errors

Errors are {"error":{"message":"…","code":"…"}}; code is present when there is a stable one.

For missing_permission, GET /accounts/{id}/health lists the account's missingPermissions and the features they block.

Endpoints

Paths are relative to https://postgale.com/api/v1.

Create a post

platforms lists 1–20 distinct accounts, each with its own platformSpecificData. Without publishNow or scheduledFor the post is a draft; publishNow: true publishes live. Host media with POST /media and use its publicUrl.

curl https://postgale.com/api/v1/posts \
  -H 'Authorization: Bearer sk_…' \
  -H 'Content-Type: application/json' \
  -H 'x-request-id: menu-2026-11-01' \
  -d @post.json

{
  "content": "New menu is live ☕",
  "scheduledFor": "2026-11-01T15:00:00Z",
  "platforms": [
    {
      "accountId": "acc_instagram",
      "platformSpecificData": {
        "mediaUrl": "https://postgale.com/media/…/menu.jpg",
        "firstComment": "#coffee #brunch"
      }
    },
    {
      "accountId": "acc_facebook_page",
      "platformSpecificData": {
        "mediaUrl": "https://postgale.com/media/…/menu.jpg"
      }
    },
    {
      "accountId": "acc_threads",
      "platformSpecificData": {
        "topicTag": "coffee",
        "replyControl": "everyone"
      }
    }
  ]
}

platformSpecificData by platform

Only the keys for the account's platform are used. Skipped options are returned as warnings on the target.

Direct messages

Instagram (Instagram API with Instagram Login) and Facebook Page Messenger conversations. The account needs instagram_business_manage_messages (Instagram) or pages_messaging (Facebook Pages); without it the endpoints that call Meta answer 403 missing_permission and accounts connected earlier must reconnect.

• Inbound: Meta webhooks deliver new messages, echoes, reads, deliveries, reactions and postbacks. Postgale stores them as conversations and messages (deduplicated by Meta message id), as inbound events of kind message, and sends the message.* webhooks below. The account must be subscribed to the messaging fields (POST /accounts/{id}/webhook-subscription).
• Messaging window: Meta only lets the business reply to someone who wrote first. Free-form messages are allowed for 24 hours after the participant's last message. With tag: "HUMAN_AGENT" a person (not automation) can reply up to 7 days after it; the Meta app needs the Human Agent permission. Outside the window POST …/messages answers 409 outside_messaging_window before anything is sent. Every conversation reports messagingWindow {open, closesAt, humanAgentClosesAt}.
• Sending: text (Instagram ≤1000, Messenger ≤2000 characters) or one attachment (mediaUrl, or mediaId of an upload; attachmentType image | video | audio | file), not both. It is a live message to a real person and cannot be edited or deleted. While approval applies it is refused with approval_required.
• Read: POST …/read sets unreadCount to 0 and sends mark_seen to Meta (only while the window is open; failures come back as warnings). Archived conversations become active again on the next inbound message.
• Sync: POST /inbox/conversations/sync backfills up to pages (default 3, max 10) × limit (default 25, max 100) conversations. Meta returns details only for the 20 most recent messages of each conversation, so older history is not available. Syncs are idempotent and emit no webhooks.

{
  "id": "cmdlv0a1b0001x2y3z4",
  "event": "message.received",
  "createdAt": "2026-10-18T09:15:02.481Z",
  "data": {
    "eventId": "cmdlv09zz0000x2y3z4",
    "platform": "instagram",
    "accountId": "acc_instagram",
    "externalId": "cust-1",
    "conversationId": "cmdluz8k70003a1b2c3",
    "messageId": "cmdlv0a0q0002x2y3z4",
    "platformMessageId": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlE",
    "platformMessageIds": [
      "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlE"
    ],
    "direction": "inbound",
    "participant": {
      "id": "1234567890123456",
      "username": "curious_shopper",
      "name": null
    },
    "text": "Hi! Do you ship to Canada?",
    "attachments": [],
    "postback": null,
    "reaction": null,
    "watermark": null,
    "sentAt": "2026-10-18T09:15:00.000Z",
    "receivedAt": "2026-10-18T09:15:02.470Z"
  }
}

Webhooks

Register an HTTPS endpoint with POST /webhooks and a list of events (default post.published, post.failed, post.pending_approval). Each delivery is a POST with the body {id, event, createdAt, data}:

• X-SocialAPI-Signature: hex HMAC-SHA256 of `${X-SocialAPI-Timestamp}.${body}` with the webhook secret.
• X-SocialAPI-Timestamp (unix seconds), X-SocialAPI-Event, X-SocialAPI-Delivery (this delivery row).
• X-Idempotency-Key: the original delivery id (also the body id), stable across retries and redeliveries.
• Any non-2xx answer or timeout (10 s) is retried with exponential backoff, up to 6 attempts. Inspect with GET /webhooks/{id}/deliveries, replay with POST /webhooks/deliveries/{deliveryId}/redeliver, check your endpoint with POST /webhooks/{id}/test.
• comment.received, mention.received and message.* need the account subscribed to Meta webhooks (POST /accounts/{id}/webhook-subscription). Comments the account itself posted are not reported.

import { createHmac, timingSafeEqual } from 'node:crypto';

const seen = new Set<string>(); // use a persistent store in production

export async function POST(request: Request) {
  const body = await request.text(); // the raw body, before JSON.parse
  const timestamp = request.headers.get('x-socialapi-timestamp') ?? '';
  const signature = request.headers.get('x-socialapi-signature') ?? '';

  // Reject stale or replayed requests (5-minute tolerance).
  if (!(Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300)) return new Response('stale', { status: 400 });

  const expected = Buffer.from(createHmac('sha256', process.env.POSTGALE_WEBHOOK_SECRET!).update(`${timestamp}.${body}`).digest('hex'));
  const actual = Buffer.from(signature);
  if (expected.length !== actual.length || !timingSafeEqual(expected, actual)) return new Response('bad signature', { status: 401 });

  // Retries and redeliveries carry the same key: process each event once.
  const key = request.headers.get('x-idempotency-key')!;
  if (seen.has(key)) return new Response('ok');
  seen.add(key);

  const { event, data } = JSON.parse(body);
  // ... handle event
  return new Response('ok');
}

Inbound Meta webhooks

For operators configuring the Meta apps of a Postgale instance. Set each product's callback URL to:

• https://postgale.com/api/webhooks/meta/instagram
• https://postgale.com/api/webhooks/meta/facebook
• https://postgale.com/api/webhooks/meta/threads
• https://postgale.com/api/webhooks/meta/whatsapp

• GET performs the verification handshake: hub.verify_token must equal META_WEBHOOK_VERIFY_TOKEN, and hub.challenge is echoed.
• POST requires a valid X-Hub-Signature-256 made with that product's app secret (INSTAGRAM_CLIENT_SECRET, FACEBOOK_APP_SECRET, THREADS_APP_SECRET; WhatsApp: WHATSAPP_APP_SECRET, then FACEBOOK_APP_SECRET); otherwise 401.
• Events are deduplicated, stored as inbound events (GET /inbox/events) and forwarded as comment.received / mention.received. Messaging events are stored as conversations and messages and forwarded as message.*.