Postocial API docs

Quickstart

These steps take you from a new key to a scheduled post. The examples use curl, and any HTTP client works the same way: replace YOUR_API_KEY and YOUR_WORKSPACE_ID with your own values.

1. Create a key. Sign in as a workspace admin, open Integrations (under Configuration in the sidebar), choose REST API, then CREATE API KEY. Name the key and tick only what it needs: for this walkthrough, publishing:accounts:read, publishing:posts:write and publishing:posts:publish. Set an expiry date if you want one, then copy the key. It is shown only once.
2. Copy your workspace ID. In the app, open Workspace Settings > Settings. Your workspace ID is under Usage in API, with a copy button. Every Publishing API URL includes it.
3. Check the key. Call GET https://app.postocial.com/os/api/ping. A valid key gets {"status":"ok"} back.

   curl https://app.postocial.com/os/api/ping \
     -H "Authorization: Bearer YOUR_API_KEY"

4. List your accounts. Call GET https://app.postocial.com/os/api/YOUR_WORKSPACE_ID/accounts and note the numeric id of each account you want to post to. An account that shows "authorized": false needs to be reconnected in the app first.

   curl https://app.postocial.com/os/api/YOUR_WORKSPACE_ID/accounts \
     -H "Authorization: Bearer YOUR_API_KEY"

5. Schedule a post. Send POST https://app.postocial.com/os/api/YOUR_WORKSPACE_ID/posts with the account ids from step 4, a date (YYYY-MM-DD), a time (HH:mm), an IANA timezone, "schedule": true and your text as the original version. If your workspace requires approval, the post waits for it.

   curl -X POST https://app.postocial.com/os/api/YOUR_WORKSPACE_ID/posts \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "accounts": [3, 7],
       "date": "2027-01-11",
       "time": "10:30",
       "timezone": "Europe/Amsterdam",
       "schedule": true,
       "versions": [
         {
           "account_id": 0,
           "is_original": true,
           "content": [{ "body": "New this week: hand-thrown mugs in four colors." }]
         }
       ]
     }'

6. Read your contacts. On Freelancer and higher plans, a key with permission to read contacts lists them with GET https://app.postocial.com/api/v1/contacts. Lists answer with data, links and meta; move through them with per_page (up to 100) and page.

   curl "https://app.postocial.com/api/v1/contacts?per_page=10" \
     -H "Authorization: Bearer YOUR_API_KEY"

Next, read how keys and permissions work, or let webhooks tell you when the post goes live.

Authentication

Every request carries a workspace API key. Only workspace admins can create keys, under Integrations > REST API.

• One workspace: a key belongs to one workspace and acts as the admin who created it, narrowed to the permissions you ticked. Your plan's features and limits still apply.
• Tied to its admin: if that admin leaves the workspace or stops being an admin, the key stops working. Create integration keys from an admin account that will stay.
• Shown once, never edited: copy the key when it appears. To change its permissions, create a new key, move your integration to it, then revoke the old one. Ticking every permission picks only the ones that exist today; permissions added later never reach existing keys.
• Up to 25 live keys per workspace.

Send the key

Put the key in one header: Authorization: Bearer YOUR_API_KEY or x-api-key: YOUR_API_KEY. A request that sends both headers with different values gets a 401.

Find the workspace

Publishing API URLs carry the workspace ID, and it must match the key's workspace: a key from another workspace gets a 404, even when its admin belongs to both. The Messaging and Link in Bio APIs take the workspace from the key, so their URLs carry no ID. With a messaging permission, GET https://app.postocial.com/api/v1/account returns the key's workspace.

Permissions

Permissions come in four groups, and none is ticked for you:

• Creating or updating a post so that it is scheduled, queued or published now also needs publishing:posts:publish.
• Changing a bio page or short link that is live also needs its publish permission.
• Keys can read custom domains but not connect them: connect and verify a domain in the app.

Personal access tokens

Personal access tokens, which you create under Access Tokens in your user menu, are for AI assistants that cannot sign in to the MCP server. A token acts as you in every workspace you belong to, so use workspace API keys for integrations.

Keep keys safe

• Use keys only on your server: never in a browser, an app bundle or a public repository.
• Give each key the fewest permissions it needs.
• Use one key per integration, so you can replace one without breaking the others.
• Before an admin leaves, replace the keys they created.

Messaging API

On Freelancer and higher plans, the Messaging API works with the same contacts and conversations as your inbox. Requests go to https://app.postocial.com/api/v1, and the key picks the workspace.

• Channels: list your connected channels and read one. Connecting a channel happens in the app.
• Contacts: create, update and delete contacts, add notes, add and remove tags, set a contact's pipeline stage, and run one action (delete, tag, untag or set a stage) on up to 500 contacts at once.
• Tags and segments: manage contact tags and saved segments. Running a segment lists the contacts that match it right now.
• Conversations: list them and read their messages, assign them, open or close them, pause the bot, block a contact, add notes and mark them read.
• Messages: send text, or an approved WhatsApp template, on the contact's channel. Sends to blocked or opted-out contacts, and free-form messages after the reply window has closed, are refused with a 422 and a reason; to reach someone on WhatsApp after that, send an approved template. An Idempotency-Key header makes a retried send go out once. Attach media by its media library id, not by URL.
• Media: upload files to the media library, list them and delete them.
• Broadcasts: create a broadcast as a draft or scheduled, for a segment or for the people an earlier broadcast reached; edit, approve, send and delete it, and read its recipients.
• Automations: list and read them, and switch them on or off. Switching one on past your plan's limit of active automations per channel answers 422.

It can't build or publish automation flows (that happens in the app; the MCP server can save drafts), list pipeline stages, custom fields, WhatsApp templates or team members, import or export contacts, or read payments, bookings and store orders, which reach you only as webhook events.

Publishing API

Every plan includes the Publishing API. Requests go to https://app.postocial.com/os/api/{workspace ID}.

• Accounts: list your connected social accounts and read one.
• Posts: create a post as a draft, or schedule it, publish it now or add it to the next free slot of your queue. Update, reschedule and approve posts, and delete them from Postocial, from the network or both, or move them to the trash. List posts 20 a page, filtered by status, keyword, account or tag.
• Tags: create, rename, recolor and delete post tags.
• Media: upload images, GIFs and videos, in chunks for large files, or import them from a URL. List, rename and delete them, and set their alt text.
• Analytics: a workspace summary, analytics per account and per post, the best times to post and each account's next best time. There are no analytics for X, Reddit, Tumblr or Telegram.

It can't connect or disconnect accounts, set the time slots of your posting schedule, reject a post, restore or duplicate a post, or filter posts by date. The MCP server can do the last three.

Link in Bio API

On every plan, the Link in Bio API builds your bio pages and short links from your own code. Requests go to https://app.postocial.com/api/v1/biolinks, and the key picks the workspace.

• Pages: create pages (they start paused, with the same starter blocks as the app), update them, change their theme, duplicate, publish or pause, and delete them.
• Blocks: add, update, reorder and remove blocks, up to 200 a page. Commerce and embed blocks can't be created or edited through the API.
• Catalog: the themes, fonts and block types you can use.
• Short links: create them (they start paused too) with a destination, slug, redirect code, UTM tags and, if you like, a password, then publish or pause them.
• QR codes: save codes for a URL, a text or a bio page. The API returns a code as a grid of cells to draw, not as an image.
• Pixels: add, list and delete the tracking pixels your pages and links use.
• Form submissions: read them, newest first with cursor paging, and delete them. There is no export through the API.
• Analytics: lifetime totals, a 7-day trend and 30-day breakdowns for a page; for a short link, the same figures count clicks. Reading analytics through the API never counts as a visit.
• Custom domains: read them. Connecting a domain happens in the app, on Freelancer and higher plans.

Two headers keep writes safe:

• Every POST needs an Idempotency-Key. The same key with the same body within 24 hours returns the first answer instead of acting twice; the same key with a different body gets a 409.
• A change to an existing page or short link needs If-Match with its current revision. A missing header gets a 428 and an outdated revision a 412: read the item again and retry.

Webhooks

Webhooks tell your server when something changes in Postocial, so you don't have to poll. Each delivery is a signed JSON POST.

Set up an endpoint

1. Open Integrations > Webhooks in the app, or use the management API at https://app.postocial.com/api/v1/workspace-webhooks.
2. Give the endpoint a name and a public HTTPS address, then pick its events. None is selected for you, and messaging events can be limited to one channel.
3. Copy the signing secret when it is shown.
4. Turn the endpoint on, since new endpoints start paused, and send a test event.

A workspace can have up to 25 endpoints.

Events

Publishing events come with every plan:

On Freelancer and higher plans, messaging events cover contacts, conversations and messages, message delivery (where the channel reports it), automations, broadcasts, payments, bookings and store orders. GET https://app.postocial.com/api/v1/workspace-webhooks/events lists every event your workspace can subscribe to, with a sample of each. Bio pages and short links send no events.

Verify the signature

Every delivery carries an X-Webhook-Signature header in the form t=<unix seconds>,v1=<hex>. The v1 value is an HMAC-SHA256 of the timestamp, a dot and the raw request body, keyed with the endpoint's signing secret. To check it:

• Use the body bytes exactly as they arrived. Parsing and re-encoding the JSON first breaks the signature.
• Reject the request when t is more than 5 minutes away from your server's clock.
• Compare the signatures in constant time.
• While a secret is being rotated, the header carries two v1 values: accept the request if either one matches.

A rotation keeps the old secret working for 24 hours by default, so you can update your server first. If a secret has leaked, rotate it with immediate effect instead, and the old one stops at once. A check in Node.js:

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

// rawBody: the request body exactly as it arrived (a Buffer), before any JSON parsing.
// header: the X-Webhook-Signature header. secret: the endpoint's signing secret.
export function verifyWebhook(rawBody, header, secret) {
  const fields = (header ?? '').split(',').map((field) => field.trim().split('='));
  const t = fields.find(([key]) => key === 't')?.[1];
  if (!Number.isInteger(Number(t)) || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = createHmac('sha256', secret).update(t + '.').update(rawBody).digest();
  return fields
    .filter(([key]) => key === 'v1')
    .some(([, hex = '']) => {
      const given = Buffer.from(hex, 'hex');
      return given.length === expected.length && timingSafeEqual(given, expected);
    });
}

Delivery

• Answer with any 2xx status within 8 seconds: store the event, then do slow work afterwards. Redirects are not followed and count as failures.
• Network errors, timeouts and 408, 429 or 5xx answers are retried, up to 6 attempts in all, after about 10 seconds, 1 minute, 5 minutes, 30 minutes and 2 hours. Other 4xx answers are final.
• Delivery is at least once: skip repeats by their X-Webhook-Delivery header.
• Events can arrive out of order: use occurred_at when order matters.
• Payloads are small on purpose. Fetch the full record through the API.
• Contact and message events can carry personal data, such as names, phone numbers and message text.

Manage endpoints from code

The management API at https://app.postocial.com/api/v1/workspace-webhooks creates, updates, tests and deletes endpoints, rotates secrets and resends deliveries. Every POST needs an Idempotency-Key header, and every change to an existing endpoint an If-Match header with its current revision. A workspace can make 60 changes a minute.

On Freelancer and higher plans, Zapier can also start Zaps from messaging events, without code: connect it under Integrations > Zapier.

MCP server

The MCP server lets an AI assistant, such as Claude, ChatGPT, Claude Code, Cursor or VS Code, work in your Postocial workspace from requests in plain language. Other apps that support MCP connect too. Its address is https://app.postocial.com/mcp (streamable HTTP), and every plan includes it.

Connect an assistant

• Sign-in: in an app with a connector screen, paste the server URL, leave any client ID and secret empty, sign in to Postocial and pick one workspace. Each connection works in that one workspace; to switch, remove the connection and add it again. The connection renews itself, and after 90 days without use you sign in again.
• Personal access token: for an app that cannot sign in, create a token under Access Tokens in your user menu and send it as Authorization: Bearer YOUR_TOKEN. A token reaches every workspace you belong to and works until you delete it, which disconnects every app that uses it.
• Claude Code: run the command below, then open /mcp in Claude Code and choose Authenticate.

claude mcp add --transport http postocial https://app.postocial.com/mcp

Step-by-step guides: Claude, ChatGPT, Claude Code, Cursor and VS Code. The MCP server overview covers the rest.

What it can do

• Workspaces and accounts: list and read them.
• Posts: list, read, create, update and duplicate posts, schedule them or publish them now, add them to the queue, delete them (also from the networks), restore them from the trash, and tag them.
• Tags and media: create and rename post tags, read your media library and add images and videos to it from a URL.
• Analytics: the workspace summary, accounts, posts and the best times to post. There are no analytics for X, Reddit, Tumblr or Telegram.
• The inbox, on Freelancer and higher plans: contacts, conversations, messages and approved WhatsApp templates, broadcasts, automations and appointments, where your team role opens those areas.

Safety rails

• It acts as you, within your role and team-role permissions: a viewer's assistant can only read.
• Posts it schedules wait for approval when your workspace requires it.
• Sending a message or a template, submitting a broadcast and closing a conversation need your explicit confirmation.
• It never sends a broadcast: a person approves it in Postocial.
• Automations it builds stay drafts until someone publishes them in the app.
• It sends at most 60 messages an hour and reaches at most 200 people a day per workspace.
• Messages from your customers reach it marked as untrusted text, with an instruction not to follow them.

What it can't do

Anything in link in bio, approving posts, deleting media, contacts, tags or automations, uploading files directly (it adds media from a URL), connecting accounts or channels, and managing webhooks. Use the REST APIs or the app for those.

Time zones

Dates are stored in UTC. The publishing tools take an IANA time zone, such as Europe/Paris; without one, they use the account's time zone, then UTC, and every answer says which one it used.

Errors and limits

Errors come back as JSON with a message. A 422 also lists errors by field, and a refused message send is a 422 with a reason.

Rate limits

The Messaging API may apply a lower limit of its own. After a 429, wait the number of seconds in the Retry-After header before you try again.

Safe retries

• A GET is always safe to repeat.
• Sending a message takes an optional Idempotency-Key, so a retried send goes out once. Link in Bio POSTs and webhook management POSTs require one.
• Other writes are not idempotent: check whether the first request worked before you retry.

Paging

• Messaging and Link in Bio lists take per_page (up to 100) and page.
• The posts list returns 20 posts a page; ask for more with page.
• The publishing media list takes limit (up to 100) and page.

Plans

A feature your plan doesn't include answers 404, even with a valid key. A limit inside a feature answers 422: for example, switching on one automation too many on a channel.