Skip to content
Postkeg

Use Postkeg from your own code

Postkeg is built around its API: your own systems post and read results over a small web API (an assistant can use the same service): posts, channels, files, results and the inbox, plus webhooks that tell you when a post goes out.

Start in two minutes

  1. Sign in, open Connections, then API keys, and make a key. Tick only what your code needs. Copy it right away: it is shown once.
  2. Send it with every call as Authorization: Bearer YOUR_API_KEY.
  3. Check that it works:
curl https://api.postkeg.com/api/v1/me \
  -H "Authorization: Bearer YOUR_API_KEY"

A key acts as the person who made it and never with more rights. If that person is later removed from the workspace, the key stops working. Every answer is JSON. Addresses start with https://api.postkeg.com/api/v1.

Connect your assistant

Claude, ChatGPT, Codex, Cursor and Gemini CLI can run tasks in Postkeg and help you build it into your app. They use the same API, as tools, and can read the developer docs. Pick yours and paste.

Claude

Claude app or claude.ai: Settings, Connectors, Add custom connector.

https://api.postkeg.com/mcp

Paste this address as the server URL, press Add, then Connect and approve Postkeg. On a Team or Enterprise plan an owner adds it under Admin settings, Connectors.

Claude Code

Run this in a terminal (add --scope user to have it in every project).

claude mcp add --transport http postkeg https://api.postkeg.com/mcp --header "Authorization: Bearer YOUR_API_KEY"

Replace YOUR_API_KEY with a key from Connections, API keys. Prefer signing in instead? Leave out the --header part, then run /mcp inside Claude Code and choose Authenticate.

ChatGPT

ChatGPT: Settings, Apps & Connectors, Advanced settings, turn on Developer mode, then Create.

https://api.postkeg.com/mcp

Name it Postkeg, paste this address as the MCP server URL, choose OAuth, and approve Postkeg when asked. Developer mode is not on every plan, and some plans can only read with custom connectors.

Codex

Add to ~/.codex/config.toml (or .codex/config.toml in a trusted project).

[mcp_servers.postkeg]
url = "https://api.postkeg.com/mcp"
bearer_token_env_var = "POSTKEG_API_KEY"

Put your API key in the POSTKEG_API_KEY environment variable before you start Codex; the file only names the variable.

Cursor

Save as .cursor/mcp.json in your project (or ~/.cursor/mcp.json for every project).

{
  "mcpServers": {
    "postkeg": {
      "url": "https://api.postkeg.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:POSTKEG_API_KEY}"
      }
    }
  }
}

Put your API key in the POSTKEG_API_KEY environment variable before you start Cursor; the file only names the variable.

Gemini CLI

Add to ~/.gemini/settings.json (or .gemini/settings.json in a project).

{
  "mcpServers": {
    "postkeg": {
      "httpUrl": "https://api.postkeg.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Replace YOUR_API_KEY with a key from Connections, API keys. Keep this file private.

Docs for your coding assistant

Building Postkeg into an app with Claude Code, Cursor, Codex or ChatGPT? Give it these plain-text docs (the guide, the full reference, code in curl, JavaScript, Python and PHP, and recipes). Connected assistants also get them as MCP resources.

Make a post

First look up the id of the channel you want to post to:

curl https://api.postkeg.com/api/v1/channels \
  -H "Authorization: Bearer YOUR_API_KEY"

Then save a draft. Nothing goes out; you can see it under Posts first.

curl -X POST https://api.postkeg.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: 6f1c2a9e-0001" \
  -H "Content-Type: application/json" \
  -d '{"body": "Hello from my own code", "channel_ids": [12]}'

Postkeg publishes immediately: call the API at the time you want the post to go out and use "mode": "publish_now". Schedule on your side. A time in the future is refused (422 scheduling_not_supported). A key without the "Publish posts" permission can only save drafts.

curl -X POST https://api.postkeg.com/api/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: 6f1c2a9e-0002" \
  -H "Content-Type: application/json" \
  -d '{"body": "Launch day", "channel_ids": [12, 15], "mode": "publish_now", "media": [{"url": "https://example.com/launch.jpg", "type": "image"}]}'

Add pictures and videos

Postkeg stores no files and has no upload endpoint (POST /media answers 410). Send your media as public https links in the post's media field and keep each link valid for at least 24 hours after the call. Attachments people send you in the inbox arrive as Postkeg links that pass the file through from the network for 24 hours: download them when the webhook arrives.

Let your customers connect their own accounts

Your app makes the content; the person who owns the Instagram, TikTok or LinkedIn account only has to say yes once. Make a connect link, give them the address, and Postkeg does the rest on a small page: no Postkeg account, no password. It works for every network (sign in at the network, pick the pages or channels, or paste a key where that is how the network works).

  1. Register the address people should come back to (once). Only addresses on this list are ever used, so nobody can turn a link into an open redirect.
curl -X POST https://api.postkeg.com/api/v1/connect-link-redirects \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://app.example.com/connected"}'
  1. Make a link for one network. Your own reference (a customer id, say) comes back to you. The key needs channels:write.
curl -X POST https://api.postkeg.com/api/v1/connect-links \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"network": "instagram", "reference": "customer-8841", "redirect_url": "https://app.example.com/connected"}'
{
  "data": {
    "id": 31,
    "status": "pending",
    "network": "instagram",
    "reference": "customer-8841",
    "url": "https://kairo.example/connect/Xk3...48 characters...",
    "expires_at": "2026-11-22T10:00:00Z"
  }
}
  1. Send the url to the account owner. It is shown only in this answer, works once, and expires after 7 days (set expires_in_days, up to 30). It ends at the first outcome: connected, or failed (the person said no, the network refused, the plan is full). Make a new link to try again, or cancel an open one with DELETE /connect-links/{id}.
  2. Afterwards the person lands on your return address with the outcome in the address, and you also get a webhook (channel.connected or channel.connect_failed). The redirect is a convenience: trust the webhook or GET /connect-links/{id}, not the address a browser carried.
https://app.example.com/connected?status=connected&channel_id=57&reference=customer-8841&connect_link_id=31
{
  "id": "evt_9a1c...",
  "type": "channel.connected",
  "created_at": "2026-11-15T10:04:12Z",
  "workspace_id": 7,
  "data": {
    "connect_link": { "id": 31, "reference": "customer-8841", "network": "instagram" },
    "channels": [ { "id": 57, "provider": "instagram", "name": "Shop on Instagram", "...": "the same channel the API shows" } ]
  }
}

Plan limits apply: a link is refused when the workspace has no room for another channel, and the number is checked again at the network. On failure error is one of access_denied, connect_failed, plan_limit, plan_expired or too_many_attempts. Links are for the workspace that made them and nothing else.

Get the numbers back into your own dashboards

Every network reports different things; Postkeg gives you one shape. Each post has views, impressions, reach, likes, comments, shares, saves, clicks, watch_time_minutes, avg_view_duration_seconds and engagements (likes + comments + shares + saves). A number the network does not share is null, never 0, so a chart can show a gap instead of a lie. All counts are lifetime totals as of collected_at; Postkeg reads the networks about every 6 hours. Keys need analytics:read. Account numbers (followers and the like) are at GET /analytics/accounts.

One post

curl "https://api.postkeg.com/api/v1/posts/345/metrics?history=true" \
  -H "Authorization: Bearer YOUR_API_KEY"
{
  "data": {
    "post_id": 345,
    "collected_at": "2026-11-15T09:00:12Z",
    "totals": { "views": 1840, "likes": 96, "comments": 7, "shares": 3, "saves": 12, "reach": null, "engagements": 118, "...": "" },
    "channels": [
      { "channel_id": 57, "network": "instagram", "url": "https://www.instagram.com/p/...",
        "collected_at": "2026-11-15T09:00:12Z",
        "metrics": { "views": 1840, "impressions": null, "reach": null, "likes": 96, "comments": 7, "shares": 3, "saves": 12, "clicks": null, "watch_time_minutes": null, "avg_view_duration_seconds": null, "engagements": 118 } }
    ]
  }
}

Everything, page by page

GET /analytics/posts lists every tracked post (also ones not made in Postkeg, where post_id is null). Filter with channel_id, post_id, network, published_from and, for an incremental pull, since (the time of your last pull). Follow next_cursor until has_more is false. Add format=csv for a spreadsheet-ready file (up to 1,000 rows a call, next cursor in the X-Next-Cursor header).

curl "https://api.postkeg.com/api/v1/analytics/posts?since=2026-11-14T00:00:00Z&limit=100" \
  -H "Authorization: Bearer YOUR_API_KEY"
curl "https://api.postkeg.com/api/v1/analytics/posts?format=csv&limit=1000" \
  -H "Authorization: Bearer YOUR_API_KEY" -D - -o posts.csv
# the next page: send the X-Next-Cursor header's value as ?cursor=

Be told instead

Subscribe a webhook to post.metrics.updated and Postkeg sends the posts whose numbers moved right after each sync, up to 50 posts a message (batch says which message of how many). Posts whose numbers did not change are not repeated.

{
  "id": "evt_5b7e...",
  "type": "post.metrics.updated",
  "created_at": "2026-11-15T09:00:14Z",
  "workspace_id": 7,
  "data": {
    "channel": { "id": 57, "network": "instagram", "provider": "instagram", "name": "Shop on Instagram" },
    "collected_at": "2026-11-15T09:00:12Z",
    "batch": { "index": 1, "of": 1 },
    "posts": [
      { "post_id": 345, "channel_id": 57, "network": "instagram", "external_id": "17895...", "collected_at": "2026-11-15T09:00:12Z",
        "metrics": { "views": 1840, "likes": 96, "...": "the same numbers as GET /posts/345/metrics" } }
    ]
  }
}

Good habits

Retry safely

Add an Idempotency-Key header (any unique text, a UUID works) to a POST. If your connection drops, send the very same request with the same key: you get the first answer back (marked Idempotent-Replayed: true) and nothing is done twice. Use a new key for a new request. A request that was refused changed nothing, so you can correct it and send it again with the same key. Keys are remembered for 24 hours.

Page through long lists

Lists return data, next_cursor and has_more. Use limit (1 to 100) and pass the cursor to get the next page.

curl "https://api.postkeg.com/api/v1/posts?status=scheduled&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
curl "https://api.postkeg.com/api/v1/posts?status=scheduled&limit=10&cursor=NEXT_CURSOR" \
  -H "Authorization: Bearer YOUR_API_KEY"

When something goes wrong

Errors always look the same, with a plain message saying what to do. Quote the request_id (also in the X-Request-Id header) if you ask for help.

{
  "error": {
    "code": "missing_scope",
    "message": "This API key does not have the posts:write scope. Create a key with it under Connections, API keys.",
    "details": { "required_scope": "posts:write" },
    "request_id": "req_3k2j1h0g9f8e7d6c5b4a3z2y"
  }
}
  • 401 the key is missing, wrong, revoked or expired.
  • 402 the plan has ended: you can still read, but not change anything.
  • 403 the key lacks a permission, or the person it acts as may not do this. workspace_suspended means the operator suspended publishing (reading still works).
  • 404 there is no such thing in this workspace.
  • 409 the same Idempotency-Key was used for a different request, or the file is in use.
  • 422 something in the request cannot be done; details says what. duplicate_content: the same text would go to too many accounts of one network within 24 hours.
  • 429 too many requests: each key may make 120 a minute and 10 a second (fair use; the operator can change it). Wait for the seconds in the Retry-After header.

What a key may do

Each key carries permissions ("scopes"). A permission that changes things also includes the matching reading one.

API key scopes
Scope What it allows
workspace:read See the workspace name, plan and who you act as.
reddit:read See the communities of a Reddit account and its preferences.
reddit:write Vote, save, report and join or leave communities as a connected Reddit account.
reddit:moderate Use the moderator tools of communities the account moderates: remove, lock, pin, flair, mod log, mod mail, rules and wiki. Off unless the operator switched moderation on.
linkedin:read See comments on any post of a LinkedIn page or profile, a page's details and its follower numbers.
linkedin:write Comment and react as a LinkedIn page or profile, and delete its own comments.
inbox:read See comments and direct messages on your channels (YouTube, Instagram, Facebook, Threads, LinkedIn Pages, X, Bluesky, Telegram, Discord, Slack).
inbox:write Write replies (they are sent at once; they need the publish permission too) and mark comments and messages handled.
inbox:reply_as_person Only for apps where a person writes each reply. Never grant to bots or automations.
whatsapp:read See WhatsApp templates, contacts and broadcasts. Conversations use the inbox permissions.
whatsapp:write Create and delete templates, import contacts and send broadcasts. Meta charges the business for the messages.
facebook:read See a Facebook Page's profile, posts, reactions, insights, Messenger settings and Page-level webhook events. Conversations and comments use the inbox permissions.
facebook:write Send rich Messenger messages (buttons, quick replies, templates), change the Page profile and Messenger settings, edit posts and comments, and block people.
instagram:read See an Instagram account's own posts, stories, profile and numbers, a person's profile in a conversation, and Instagram events (reactions, button taps, live comments).
instagram:write Send messages with buttons, set the ice breakers and menu, switch comments on or off, and (with Facebook Login) delete posts, like and answer collaboration invites.
threads:read Browse the account's posts, replies and mentions, see insights, search, and look up locations and profiles (when allowed). Replies in the inbox use the inbox permissions.
threads:write Repost, delete posts and approve or ignore pending replies.
x:read Read the connected X account's bookmarks, lists, followers, following, muted and blocked accounts and its email (each needs its permission switched on for the server and allowed on the account; X charges for reads).
x:write Hide replies, bookmark, repost, quote and reply, manage lists, follow, mute and block as the connected X account (X charges for each action; Postkeg passes it on).
youtube:read See a YouTube channel's video details, playlists, channel sections, revenue numbers and members (each when the channel allowed it).
youtube:write Change video details, manage playlists and their videos, and moderate or delete comments (each when the channel allowed it).
analytics:read See how your posts and channels did (views, reach, likes, followers, best posts) and how your goals are going.
analytics:write Set and remove results goals (a target for followers, views or likes of a channel).
ads:read See ad accounts, campaigns, ad sets and ads, and their reports (spend, reach, clicks, results).
ads:write Start and stop ads, change budgets and boost posts. The business pays the network directly.
leads:read See the people who filled in your ad lead forms, with what they answered (personal data).
leads:write Change the status of a lead and add notes.
channels:read See your connected channels, their health and connect links.
channels:write Rename and disconnect channels and make connect links.
posts:read See posts, drafts, and their results.
posts:write Create, edit, schedule, move, cancel, duplicate and delete posts. Without Publish posts it can only save drafts.
posts:publish Schedule posts and send them out straight away, retry failed ones, publish replies. Without it only drafts can be saved.
media:read Postkeg stores no files, so nothing is left to see with this. It is only kept so keys that have it keep working.
media:write Postkeg stores no files, so there is nothing to manage with this. It is only kept so keys that have it keep working.
webhooks:read See the addresses Postkeg sends events to.
webhooks:write Add and delete the addresses Postkeg sends events to.
automations:read See your automations (rules and journeys that answer comments and messages), the people in journeys and what they did.
automations:write Create, change, switch on and off and delete automations, and take people out of journeys. Their replies are only sent when the key or connection holds the publish permission.

Everything you can call

The full, machine-readable description is at /api/v1/openapi.json (OpenAPI 3.1): import it into Postman, Insomnia or a code generator.

Workspace

Workspace endpoints
Call Needs What it does
GET /me workspace:read Who this key is
GET /plan workspace:read Plan and usage
GET /billing workspace:read Subscription status
GET /wallet workspace:read X balance
GET /wallet/entries workspace:read X balance ledger
POST /wallet/top-ups workspace:read Top up the X balance

Posts

Posts endpoints
Call Needs What it does
GET /posts posts:read List posts
POST /posts posts:write Create a post
POST /posts/bulk posts:write Create up to 100 posts
GET /posts/{post} posts:read Get a post
PATCH /posts/{post} posts:write Change a post
POST /posts/{post}/move posts:write Set a time for a post
POST /posts/{post}/cancel posts:write Cancel a post
POST /posts/by-external-id/{external_id}/cancel posts:write Cancel a post by external_id
DELETE /posts/by-external-id/{external_id} posts:write Delete a post by external_id
POST /posts/{post}/duplicate posts:write Duplicate a post
DELETE /posts/{post} posts:write Delete a post
POST /posts/{post}/publish posts:publish Publish a post now
PATCH /posts/{post}/channels/{channel} posts:publish Edit a published post on one network
DELETE /posts/{post}/channels/{channel} posts:publish Delete a post from one network
POST /posts/{post}/channels/{channel}/retry posts:publish Retry a failed channel

Channels

Channels endpoints
Call Needs What it does
GET /channels channels:read List channels
GET /channels/{channel} channels:read Get a channel
PATCH /channels/{channel} channels:write Rename a channel, tag it with a tenant, or switch X reading
DELETE /channels/{channel} channels:write Disconnect a channel
POST /channels channels:write Make a test channel (test keys only)
POST /connect-links channels:write Make a connect link
GET /connect-links channels:read List connect links
GET /connect-links/{link} channels:read Get a connect link
DELETE /connect-links/{link} channels:write Cancel a connect link
GET /connect-link-redirects channels:read List return addresses
POST /connect-link-redirects channels:write Add a return address
DELETE /connect-link-redirects/{redirect} channels:write Remove a return address

Inbox

Inbox endpoints
Call Needs What it does
GET /inbox/threads inbox:read List comment threads
GET /inbox/counts inbox:read Count open and unread threads
GET /inbox/accounts inbox:read What each channel can do in the inbox
GET /inbox/messages inbox:read List stored messages
POST /inbox/messages/{message}/actions inbox:write Hide, show, delete or like a message
GET /inbox/threads/{thread} inbox:read Get a thread
POST /inbox/threads/{thread}/replies inbox:write Reply to a thread
POST /inbox/read-all inbox:write Mark everything read
POST /inbox/threads/{thread}/read inbox:write Mark a thread read or unread
POST /inbox/threads/{thread}/handled inbox:write Mark a thread handled
POST /inbox/threads/{thread}/moderation inbox:write Hide, show, delete or like a comment

Events

Events endpoints
Call Needs What it does
GET /events workspace:read Poll events
GET /events/stream workspace:read Stream events (Server-Sent Events)
POST /events/stream-tokens workspace:read Make a stream token

Automations

Automations endpoints
Call Needs What it does
GET /automations automations:read List automations
POST /automations automations:write Create an automation
GET /automations/{automation} automations:read Get an automation
PATCH /automations/{automation} automations:write Change an automation
DELETE /automations/{automation} automations:write Delete an automation
GET /automations/{automation}/runs automations:read Log of an automation
GET /journeys automations:read List journeys
POST /journeys automations:write Create a journey
GET /journeys/{journey} automations:read Get a journey
PATCH /journeys/{journey} automations:write Change a journey
DELETE /journeys/{journey} automations:write Delete a journey
GET /journeys/{journey}/runs automations:read People in a journey
GET /journeys/{journey}/log automations:read Log of a journey
DELETE /journeys/{journey}/runs/{run} automations:write Take a person out of a journey

Analytics

Analytics endpoints
Call Needs What it does
GET /posts/{post}/metrics analytics:read Numbers of one post
GET /analytics/posts analytics:read Export numbers of all posts
GET /analytics/accounts analytics:read Followers and account numbers per channel
GET /analytics/accounts/{channel}/history analytics:read Daily history of one channel
GET /goals analytics:read List goals
POST /goals analytics:write Set a goal
DELETE /goals/{goal} analytics:write Delete a goal

Leads

Leads endpoints
Call Needs What it does
GET /leads leads:read List leads
GET /leads/{lead} leads:read Get a lead
PATCH /leads/{lead} leads:write Change a lead
DELETE /leads/{lead} leads:write Delete a lead

Ads

Ads endpoints
Call Needs What it does
GET /ad-accounts ads:read List ad accounts
GET /ad-accounts/{adAccount} ads:read Get an ad account
DELETE /ad-accounts/{adAccount} ads:write Disconnect an ad account
POST /ad-connect-links ads:write Make an ad connect link
GET /ad-connect-links/{link} ads:read Get an ad connect link
GET /ad-accounts/{adAccount}/objects ads:read List campaigns, ad sets or ads
GET /ad-accounts/{adAccount}/locations ads:read Search places for a boost
GET /ad-accounts/{adAccount}/catalogs ads:read List product catalogs
POST /ad-accounts/{adAccount}/catalogs ads:write Make a product catalog
GET /ad-accounts/{adAccount}/catalogs/feeds ads:read List product feeds
POST /ad-accounts/{adAccount}/catalogs/feeds ads:write Make a product feed
PATCH /ad-accounts/{adAccount}/catalogs/feeds/{feed} ads:write Change a product feed
DELETE /ad-accounts/{adAccount}/catalogs/feeds/{feed} ads:write Delete a product feed
POST /ad-accounts/{adAccount}/catalogs/feeds/{feed}/ingest ads:write Fetch a product feed now
GET /ad-accounts/{adAccount}/catalogs/feeds/{feed}/processing-results ads:read Product feed processing results
GET /ad-accounts/{adAccount}/insights ads:read Report on campaigns, ad sets or ads
PATCH /ad-accounts/{adAccount}/objects/{object} ads:write Pause, resume or change a budget
POST /ad-accounts/{adAccount}/boosts ads:write Boost a published post

Webhooks

Webhooks endpoints
Call Needs What it does
GET /webhooks webhooks:read List webhooks
POST /webhooks webhooks:write Add a webhook
PATCH /webhooks/{webhook} webhooks:write Rename a Postcraft link
GET /webhooks/{webhook}/deliveries webhooks:read List deliveries of a webhook
POST /webhooks/deliveries/{delivery}/redeliver webhooks:write Send an event again
DELETE /webhooks/{webhook} webhooks:write Delete a webhook

WhatsApp

WhatsApp endpoints
Call Needs What it does
GET /whatsapp/numbers whatsapp:read List WhatsApp numbers
GET /whatsapp/templates whatsapp:read List templates
GET /whatsapp/templates/{template} whatsapp:read Get a template
POST /whatsapp/templates whatsapp:write Create a template
PATCH /whatsapp/templates/{template} whatsapp:write Edit a template
POST /whatsapp/templates/sync whatsapp:write Reload templates from Meta
DELETE /whatsapp/templates/{template} whatsapp:write Delete a template
GET /whatsapp/contacts whatsapp:read List contacts
POST /whatsapp/contacts whatsapp:write Add or update a contact
POST /whatsapp/contacts/import whatsapp:write Import contacts from CSV
PATCH /whatsapp/contacts/{contact} whatsapp:write Change a contact
DELETE /whatsapp/contacts/{contact} whatsapp:write Remove a contact
GET /whatsapp/broadcasts whatsapp:read List broadcasts
POST /whatsapp/broadcasts whatsapp:write Create a broadcast
POST /whatsapp/broadcasts/estimate whatsapp:read Estimate a broadcast
GET /whatsapp/broadcasts/{broadcast} whatsapp:read Get a broadcast
POST /whatsapp/broadcasts/{broadcast}/cancel whatsapp:write Cancel a broadcast
GET /whatsapp/broadcasts/{broadcast}/recipients whatsapp:read List recipients
POST /whatsapp/numbers/{channel}/messages whatsapp:write Send a message of any type
POST /whatsapp/numbers/{channel}/typing whatsapp:write Show the typing indicator
GET /whatsapp/messages/payloads whatsapp:read List structured inbound data
POST /whatsapp/numbers/{channel}/media whatsapp:write Upload media
DELETE /whatsapp/numbers/{channel}/media/{media} whatsapp:write Delete uploaded media
GET /whatsapp/numbers/{channel}/profile whatsapp:read Get the business profile
PATCH /whatsapp/numbers/{channel}/profile whatsapp:write Change the business profile
GET /whatsapp/numbers/{channel}/qr-codes whatsapp:read List QR codes and message links
POST /whatsapp/numbers/{channel}/qr-codes whatsapp:write Create a QR code
PATCH /whatsapp/numbers/{channel}/qr-codes/{code} whatsapp:write Change a QR code
DELETE /whatsapp/numbers/{channel}/qr-codes/{code} whatsapp:write Delete a QR code
GET /whatsapp/numbers/{channel}/blocks whatsapp:read List blocked people
POST /whatsapp/numbers/{channel}/blocks whatsapp:write Block people
DELETE /whatsapp/numbers/{channel}/blocks whatsapp:write Unblock people
GET /whatsapp/numbers/{channel}/commerce whatsapp:read Commerce settings and catalogs
PATCH /whatsapp/numbers/{channel}/commerce whatsapp:write Change commerce settings
GET /whatsapp/flows whatsapp:read List Flows
POST /whatsapp/flows whatsapp:write Create a Flow
POST /whatsapp/flows/{flow}/publish whatsapp:write Publish a Flow
POST /whatsapp/flows/{flow}/deprecate whatsapp:write Deprecate a Flow
DELETE /whatsapp/flows/{flow} whatsapp:write Delete a draft Flow
POST /whatsapp/numbers/{channel}/direct-send whatsapp:write Direct Send (utility)
GET /whatsapp/numbers/{channel}/marketing-messages whatsapp:read Marketing Messages API state
POST /whatsapp/numbers/{channel}/marketing-messages/check whatsapp:write Check Marketing Messages API onboarding
POST /whatsapp/numbers/{channel}/marketing-messages/send whatsapp:write Send a marketing template through the Marketing Messages API
GET /whatsapp/numbers/{channel}/settings whatsapp:read Number settings
POST /whatsapp/numbers/{channel}/two-step-pin whatsapp:write Set or change the two-step verification PIN
POST /whatsapp/numbers/{channel}/display-name whatsapp:write Ask for a new display name
POST /whatsapp/numbers/{channel}/verification-code whatsapp:write Request a verification code
POST /whatsapp/numbers/{channel}/verify-code whatsapp:write Verify the code
POST /whatsapp/numbers/{channel}/identity-check whatsapp:write Identity change check
POST /whatsapp/numbers/{channel}/template-assets whatsapp:write Upload a template header sample
GET /whatsapp/numbers/{channel}/flow-endpoint whatsapp:read Flow data-exchange endpoint
POST /whatsapp/numbers/{channel}/flow-endpoint whatsapp:write Create or change the Flow endpoint
POST /whatsapp/numbers/{channel}/flow-endpoint/check whatsapp:write Check the Flow endpoint key
DELETE /whatsapp/numbers/{channel}/flow-endpoint whatsapp:write Remove the Flow endpoint
POST /whatsapp/numbers/{channel}/conversion-events whatsapp:write Send a conversion event to Meta
GET /whatsapp/analytics/messaging whatsapp:read Messaging analytics
GET /whatsapp/analytics/pricing whatsapp:read Pricing analytics
GET /whatsapp/analytics/templates whatsapp:read Template analytics

Facebook

Facebook endpoints
Call Needs What it does
POST /facebook/{channel}/messages facebook:write Send a Messenger message
POST /facebook/{channel}/messages/react facebook:write React to a Messenger message
POST /facebook/{channel}/typing facebook:write Show typing or mark as seen
POST /facebook/{channel}/attachments facebook:write Upload a reusable attachment
GET /facebook/{channel}/personas facebook:read List personas
POST /facebook/{channel}/personas facebook:write Create a persona
DELETE /facebook/{channel}/personas/{persona} facebook:write Delete a persona
GET /facebook/{channel}/messenger-profile facebook:read Read the Messenger profile
PUT /facebook/{channel}/messenger-profile facebook:write Change the Messenger profile
DELETE /facebook/{channel}/messenger-profile facebook:write Remove Messenger profile fields
GET /facebook/{channel}/messaging-features facebook:read Messaging features Meta approved
GET /facebook/{channel}/profile facebook:read Read the Page profile
PATCH /facebook/{channel}/profile facebook:write Change the Page profile
GET /facebook/{channel}/posts facebook:read Browse the Page's posts
GET /facebook/{channel}/public-pages/{page} facebook:read Read another public Page
GET /facebook/{channel}/public-pages/{page}/posts facebook:read Recent posts of another public Page
POST /facebook/{channel}/posts/{post} facebook:write Edit a post's text
GET /facebook/{channel}/reactions facebook:read Reactions on a post or comment
GET /facebook/{channel}/insights facebook:read Page and post insights
GET /facebook/{channel}/integrity facebook:read Page integrity status
POST /facebook/{channel}/blocked facebook:write Block a person on the Page
DELETE /facebook/{channel}/blocked facebook:write Unblock a person
POST /facebook/{channel}/comments/{comment} facebook:write Edit a comment the Page wrote
POST /facebook/{channel}/comments/{comment}/replies facebook:write Reply to a comment, with a picture or GIF
GET /facebook/{channel}/videos/{video} facebook:read Read a Page video
POST /facebook/{channel}/videos/{video} facebook:write Change a video's title or description
POST /facebook/{channel}/videos/{video}/thumbnail facebook:write Add a custom video thumbnail
GET /facebook/{channel}/videos/{video}/captions facebook:read List a video's captions
POST /facebook/{channel}/videos/{video}/captions facebook:write Upload SRT captions
DELETE /facebook/{channel}/videos/{video}/captions facebook:write Delete captions of one locale
POST /facebook/{channel}/videos/{video}/crosspost facebook:write Crosspost a video to other Pages
GET /facebook/{channel}/thread-owner facebook:read Which app controls a Messenger thread
POST /facebook/{channel}/thread-control facebook:write Pass, take, request, release or extend thread control
GET /facebook/{channel}/notifications facebook:read Notification messages opt-ins
POST /facebook/{channel}/notifications/request facebook:write Ask a person to opt in to notifications
POST /facebook/{channel}/notifications/send facebook:write Send a notification
GET /facebook/{channel}/templates facebook:read List Messenger utility templates
POST /facebook/{channel}/templates facebook:write Create a Messenger utility template
POST /facebook/{channel}/templates/send facebook:write Send a Messenger utility template
GET /facebook/{channel}/live-videos facebook:read List the Page's live videos
POST /facebook/{channel}/live-videos facebook:write Create a live video
POST /facebook/{channel}/live-videos/{video}/end facebook:write End a live video
GET /facebook/{channel}/call-to-action facebook:read Read the Page's call-to-action button
PUT /facebook/{channel}/call-to-action facebook:write Set the Page's call-to-action button
DELETE /facebook/{channel}/call-to-action/{cta} facebook:write Remove the Page's call-to-action button
POST /facebook/{channel}/webhook-subscription facebook:write Subscribe the Page to every webhook field

Instagram

Instagram endpoints
Call Needs What it does
GET /instagram/{channel}/profile instagram:read Read the account's profile
GET /instagram/{channel}/media instagram:read List the account's own media
GET /instagram/{channel}/media/{media} instagram:read Read one media
GET /instagram/{channel}/insights instagram:read Read Instagram insights
POST /instagram/{channel}/media/{media} instagram:write Switch comments on or off
DELETE /instagram/{channel}/media/{media} instagram:write Delete a post, Reel or story
GET /instagram/{channel}/users/{igsid} instagram:read Read a person's profile
POST /instagram/{channel}/messages instagram:write Send a message
POST /instagram/{channel}/typing instagram:write Show typing or mark as read
POST /instagram/{channel}/reactions instagram:write React to a message
GET /instagram/{channel}/messenger-profile instagram:read Read ice breakers and the menu
PUT /instagram/{channel}/messenger-profile instagram:write Set ice breakers and the menu
DELETE /instagram/{channel}/messenger-profile instagram:write Remove ice breakers or the menu
POST /instagram/{channel}/conversations/{igsid}/moderation instagram:write Block, unblock or mark a conversation as spam
POST /instagram/{channel}/likes instagram:write Like a post or comment
DELETE /instagram/{channel}/likes instagram:write Remove a like
GET /instagram/{channel}/tags instagram:read Posts the account is tagged in
GET /instagram/{channel}/collaboration-invites instagram:read List collaboration invites
POST /instagram/{channel}/collaboration-invites/{media} instagram:write Accept or decline an invite
GET /instagram/{channel}/discover instagram:read Look up another business account
GET /instagram/{channel}/hashtags instagram:read Find a hashtag id
GET /instagram/{channel}/hashtags/{hashtag}/media instagram:read Posts of a hashtag
GET /instagram/{channel}/locations instagram:read Find a place to tag
GET /instagram/{channel}/catalogs instagram:read List product catalogs to tag from
GET /instagram/{channel}/catalogs/products instagram:read Find a product to tag
GET /instagram/{channel}/branded-content/creators instagram:read List the creators a brand approved
POST /instagram/{channel}/branded-content/creators instagram:write Approve creators for branded content
DELETE /instagram/{channel}/branded-content/creators instagram:write Remove approved creators
GET /instagram/oembed instagram:read Embed code of a public post

Threads

Threads endpoints
Call Needs What it does
GET /threads/{channel}/posts threads:read List the account's posts
GET /threads/{channel}/posts/{external_id} threads:read Get a post
GET /threads/{channel}/replies threads:read List the account's own replies
GET /threads/{channel}/mentions threads:read List mentions
GET /threads/{channel}/ghost-posts threads:read List ghost posts
GET /threads/{channel}/posts/{external_id}/pending-replies threads:read List pending replies
POST /threads/{channel}/pending-replies/{external_id}/approve threads:write Approve a pending reply
POST /threads/{channel}/pending-replies/{external_id}/ignore threads:write Ignore a pending reply
POST /threads/{channel}/posts/{external_id}/repost threads:write Repost a post
DELETE /threads/{channel}/posts/{external_id} threads:write Delete a post or repost
GET /threads/{channel}/insights threads:read Read insights
GET /threads/{channel}/locations threads:read Search locations
GET /threads/{channel}/search threads:read Search public posts
GET /threads/{channel}/profile threads:read Look up a public profile
GET /threads/oembed threads:read Get embed code
GET /threads/trending threads:read List trending topics
GET /threads/trending/{external_id}/posts threads:read List posts of a trend

Reddit

Reddit endpoints
Call Needs What it does
GET /reddit/{channel}/subreddits reddit:read List the account's communities
GET /reddit/{channel}/prefs reddit:read Read the account's preferences
POST /reddit/{channel}/things/{thing}/vote reddit:write Upvote, downvote or take a vote back
POST /reddit/{channel}/things/{thing}/save reddit:write Save or unsave a post or comment
POST /reddit/{channel}/things/{thing}/report reddit:write Report a post or comment
PUT /reddit/{channel}/subreddits/{subreddit}/subscription reddit:write Join or leave a community
POST /reddit/{channel}/things/{thing}/moderation reddit:moderate Moderate a post or comment
POST /reddit/{channel}/subreddits/{subreddit}/flair reddit:moderate Set the flair of a post or user
GET /reddit/{channel}/subreddits/{subreddit}/modlog reddit:moderate Read the moderation log
GET /reddit/{channel}/modmail/conversations reddit:moderate List mod mail conversations
GET /reddit/{channel}/modmail/conversations/{conversation} reddit:moderate Read a mod mail conversation
POST /reddit/{channel}/modmail/conversations/{conversation}/replies reddit:moderate Reply in a mod mail conversation
GET /reddit/{channel}/subreddits/{subreddit}/config reddit:moderate Read a community's rules and settings
GET /reddit/{channel}/subreddits/{subreddit}/wiki/{page} reddit:moderate Read a wiki page
PUT /reddit/{channel}/subreddits/{subreddit}/wiki/{page} reddit:moderate Edit a wiki page

LinkedIn

LinkedIn endpoints
Call Needs What it does
GET /linkedin/{channel}/posts/{post}/comments linkedin:read List the comments of a post
POST /linkedin/{channel}/posts/{post}/comments linkedin:write Comment on a post
DELETE /linkedin/{channel}/posts/{post}/comments/{comment} linkedin:write Delete a comment the channel wrote
PUT /linkedin/{channel}/reactions linkedin:write React to a post or comment
GET /linkedin/{channel}/organization linkedin:read Read the company page's details
GET /linkedin/{channel}/followers linkedin:read Follower count and gains of a company page

X

X endpoints
Call Needs What it does
GET /x/{channel}/account x:read Get the account and its email
GET /x/{channel}/bookmarks x:read List bookmarks
GET /x/{channel}/lists x:read List the account's own lists
GET /x/{channel}/lists/{list} x:read Get a list
GET /x/{channel}/lists/{list}/members x:read List the members of a list
GET /x/{channel}/lists/{list}/posts x:read List the posts of a list
GET /x/{channel}/followers x:read List followers
GET /x/{channel}/following x:read List who the account follows
GET /x/{channel}/muted x:read List muted accounts
GET /x/{channel}/blocked x:read List blocked accounts
POST /x/{channel}/posts/{post}/hide x:write Hide a reply
POST /x/{channel}/posts/{post}/unhide x:write Show a hidden reply again
POST /x/{channel}/posts/{post}/bookmark x:write Bookmark a post
DELETE /x/{channel}/posts/{post}/bookmark x:write Remove a bookmark
POST /x/{channel}/posts/{post}/repost x:write Repost a post
DELETE /x/{channel}/posts/{post}/repost x:write Take back a repost
POST /x/{channel}/quotes x:write Quote a post
POST /x/{channel}/replies x:write Reply to a post
POST /x/{channel}/lists x:write Create a list
PATCH /x/{channel}/lists/{list} x:write Change a list
DELETE /x/{channel}/lists/{list} x:write Delete a list
POST /x/{channel}/lists/{list}/members x:write Add a list member
DELETE /x/{channel}/lists/{list}/members/{user} x:write Remove a list member
POST /x/{channel}/follows x:write Follow a person
DELETE /x/{channel}/follows/{user} x:write Unfollow a person
POST /x/{channel}/mutes x:write Mute a person
DELETE /x/{channel}/mutes/{user} x:write Unmute a person
POST /x/{channel}/blocks x:write Block a person
DELETE /x/{channel}/blocks/{user} x:write Unblock a person

YouTube

YouTube endpoints
Call Needs What it does
GET /youtube/{channel}/videos/{video} youtube:read Read a video
PATCH /youtube/{channel}/videos/{video} youtube:write Change a video's details
POST /youtube/{channel}/videos/{video}/thumbnail youtube:write Set a custom thumbnail from a link
GET /youtube/{channel}/playlists youtube:read List playlists
POST /youtube/{channel}/playlists youtube:write Create a playlist
PATCH /youtube/{channel}/playlists/{playlist} youtube:write Change a playlist
DELETE /youtube/{channel}/playlists/{playlist} youtube:write Delete a playlist
GET /youtube/{channel}/playlists/{playlist}/items youtube:read List a playlist's videos
POST /youtube/{channel}/playlists/{playlist}/items youtube:write Add a video to a playlist
DELETE /youtube/{channel}/playlists/{playlist}/items/{item} youtube:write Remove a video from a playlist
POST /youtube/{channel}/comments/moderate youtube:write Hold, publish or reject comments
DELETE /youtube/{channel}/comments/{comment} youtube:write Delete a comment
GET /youtube/{channel}/sections youtube:read Read the channel's homepage sections
GET /youtube/{channel}/revenue youtube:read Revenue numbers
GET /youtube/{channel}/membership-levels youtube:read List membership levels
GET /youtube/{channel}/members youtube:read List channel members

Webhooks: hear about posts without asking

Instead of asking again and again whether a post went out, give Postkeg an address and it tells you. Add one under Connections, Webhooks. The address must start with https://.

Postkeg announces every change, so you can automate from them. Tick the ones you want when you add the webhook, or use a whole group such as inbox.* (or * for everything). Every event with its full message is in the webhooks document and the OpenAPI description.

whatsapp.message.status
A WhatsApp message changed state.
whatsapp.template.status
A WhatsApp template changed state.
whatsapp.broadcast.finished
A WhatsApp broadcast finished.
whatsapp.contact.opted_out
A WhatsApp contact opted out.
whatsapp.message.payload
A WhatsApp message carried structured data.
whatsapp.template.quality
A WhatsApp template quality changed.
whatsapp.account.alert
A WhatsApp account alert.
whatsapp.account.review
A WhatsApp account review decision.
whatsapp.phone.name
A WhatsApp display name decision.
whatsapp.contact.preference
A WhatsApp person changed their marketing preference.
whatsapp.contact.identity
A WhatsApp person changed their number or user id.
whatsapp.account.security
A WhatsApp two-step verification event.
whatsapp.account.capability
A WhatsApp business limit changed.
whatsapp.template.components
A WhatsApp template's content changed.
whatsapp.partner.solution
A WhatsApp partner solution changed.
whatsapp.automatic_event
A WhatsApp ad conversion event.
whatsapp.payment.configuration
A WhatsApp payment configuration changed.
whatsapp.handover
A WhatsApp conversation changed owner.
whatsapp.flow.status
A WhatsApp Flow changed or its endpoint health changed.
whatsapp.flow.error
A WhatsApp Flow reported an error to the data-exchange endpoint.
whatsapp.phone.quality
A WhatsApp number's limit or throughput changed.
whatsapp.marketing_messages.status
A WhatsApp number's Marketing Messages API state changed.
messenger.delivery
A Messenger message was delivered.
messenger.read
A Messenger message was read.
messenger.reaction
Somebody reacted to a Messenger message.
messenger.postback
A Messenger button was pressed.
messenger.referral
A Messenger conversation started from a link or ad.
messenger.optin
Somebody opted in on Messenger.
messenger.feedback
A person rated an answer on Messenger.
messenger.policy
Meta warned or blocked the Page's messaging.
facebook.page.integrity
The Page's integrity status changed.
facebook.video.status
A Page video changed processing status.
facebook.live_video.status
A Page live video changed status.
facebook.conversation.updated
A Page conversation changed.
facebook.publisher_subscription
A Page publisher subscription changed.
facebook.page_change_proposal
Meta proposed a change to the Page.
messenger.handover
Messenger thread control changed.
messenger.standby
A conversation event arrived while another app owns the thread.
messenger.template.status
A Messenger utility template changed status.
facebook.feed.post
Page feed: post.
facebook.feed.status
Page feed: status.
facebook.feed.photo
Page feed: photo.
facebook.feed.video
Page feed: video.
facebook.feed.share
Page feed: share.
facebook.feed.reaction
Page feed: reaction.
instagram.message.reaction
An Instagram message got a reaction.
instagram.message.seen
An Instagram message was read.
instagram.message.postback
An Instagram button or ice breaker was tapped.
instagram.message.referral
An Instagram conversation started from a link.
instagram.message.optin
An Instagram person opted in to messages.
instagram.handover
Another app took or gave back an Instagram conversation.
instagram.standby
An Instagram message arrived while another app owns the conversation.
instagram.live_comment
A comment on an Instagram live video.
instagram.story.insights
Numbers of an Instagram story that just ended.
threads.post.published
A Threads post was published.
threads.post.deleted
A Threads post was deleted.
post.created
A post was created.
post.updated
A post was changed.
post.scheduled
A post was scheduled.
post.cancelled
A post was cancelled.
post.published
A post went out.
post.partially_published
A post went out on some channels.
post.failed
A post failed.
post.rejected
A network refused a post.
post.deleted
A post was deleted.
post.metrics.updated
Post numbers changed.
channel.connected
An account was connected.
channel.connect_failed
Connecting an account failed.
channel.reconnected
A channel works again.
channel.needs_reconnect
A channel needs to be reconnected.
channel.token_expiring
A channel connection ends soon.
channel.x_reading.limit
An X account reached its reading allowance.
channel.disconnected
A channel was disconnected.
inbox.item.received
An item arrived.
inbox.item.updated
An item was edited.
inbox.item.deleted
An item was deleted.
inbox.thread.handled
A conversation was marked handled.
inbox.thread.read
A conversation was read.
inbox.threads.read
Many conversations were marked read.
inbox.comment.hidden
A comment was hidden.
inbox.comment.unhidden
A comment was shown again.
inbox.comment.deleted
A comment was deleted.
inbox.reply.sent
A reply went out.
inbox.reply.failed
A reply could not be sent.
inbox.dm_window.closing
A message window closes soon.
ad_account.connected
An ad account was connected.
ad_account.disconnected
An ad account was disconnected.
ad_account.needs_reconnect
An ad account needs to be reconnected.
ad.boost.started
A boost started.
ad.boost.failed
A boost failed.
ad.boost.finished
A boost finished.
ad.status_changed
An ad was paused or resumed.
ad.budget_changed
A budget was changed.
lead.received
A lead arrived.
account.goal_reached
A goal was reached.
billing.subscription.updated
The subscription changed.
wallet.balance.low
The X balance is running low.
wallet.balance.empty
An X charge was refused: balance too low.
wallet.topped_up
The X balance was topped up.
workspace.allowance.reached
An account reached its monthly allowance.
workspace.publishing.paused
Publishing was paused.
workspace.publishing.resumed
Publishing resumed.
automation.run
An automation ran.
journey.started
A journey started.
journey.step
A journey step ran.
journey.completed
A journey ended well.
journey.failed
A journey failed.
journey.ai_requested
Your AI was asked.

Each message is a small JSON document:

{
  "id": "evt_4f9a1c2b7d8e0f3a5b6c7d8e",
  "type": "post.published",
  "created_at": "2026-11-12T08:30:04Z",
  "workspace_id": 7,
  "data": { "post": { "id": 345, "status": "published", "...": "the same post the API shows" } }
}

Check that it really came from Postkeg

Every message has an X-Postkeg-Signature header: v1= followed by an HMAC-SHA256 (hex) of the timestamp, a dot and the raw body, made with the signing secret you saw when you added the webhook. The timestamp is in X-Postkeg-Timestamp (seconds). Refuse a message whose timestamp is more than 5 minutes old, so a copy someone captured cannot be sent again later. Other headers: X-Postkeg-Event, X-Postkeg-Event-Id (the same on a resend: keep ids to skip repeats) and X-Postkeg-Attempt.

<?php
$secret    = getenv('POSTKEG_WEBHOOK_SECRET');           // whsec_...
$body      = file_get_contents('php://input');          // the raw text, before decoding
$timestamp = $_SERVER['HTTP_X_POSTKEG_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_POSTKEG_SIGNATURE'] ?? '';

$expected = 'v1=' . hash_hmac('sha256', $timestamp . '.' . $body, $secret);

if (!ctype_digit($timestamp) || abs(time() - (int) $timestamp) > 300
    || !hash_equals($expected, $signature)) {
    http_response_code(401);
    exit;
}

$event = json_decode($body, true);
// Skip it if you already handled $event['id'], do your work, then:
http_response_code(200);
import crypto from 'node:crypto';

// Express: use express.raw({ type: 'application/json' }) so req.body is the raw text.
export function isFromPostkeg(req, secret) {
  const timestamp = req.get('X-Postkeg-Timestamp') ?? '';
  const signature = req.get('X-Postkeg-Signature') ?? '';
  const body = req.body.toString('utf8');

  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300;
  const expected = 'v1=' + crypto.createHmac('sha256', secret).update(timestamp + '.' + body).digest('hex');
  const a = Buffer.from(expected);
  const b = Buffer.from(signature);

  return fresh && a.length === b.length && crypto.timingSafeEqual(a, b);
}
import hmac, hashlib, time

def is_from_postkeg(raw_body: bytes, timestamp: str, signature: str, secret: str) -> bool:
    if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > 300:
        return False
    signed = timestamp.encode() + b'.' + raw_body
    expected = 'v1=' + hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

What Postkeg does when you do not answer

Answer with any 2xx status within 5 seconds. Otherwise Postkeg tries again after 1 minute, 5 minutes, 30 minutes and 6 hours: five tries in all. Redirects are not followed, so give the final address. If several events in a row cannot be delivered, the webhook is switched off and the owner gets an email; fix the address and switch it on again. The page lists every delivery and lets you send one again, or send a test.

The delivery log, and sending again

Postkeg keeps every delivery and every try for 30 days, with the answer code, how long your server took and the start of its answer. Read it with GET /webhooks/{id}/deliveries and send an event again with POST /webhooks/deliveries/{id}/redeliver (it keeps the same event id). A webhook that has failed for 3 days is switched off too.