llms.txt
# Postproxy - Unified API for Social Media Publishing, Comments, DMs, and Reviews
> Website: https://postproxy.dev
> API: https://api.postproxy.dev
> App: https://app.postproxy.dev
> GitHub: https://github.com/postproxy
Postproxy is a unified social media API for the full lifecycle: publish content, then manage comments, direct messages, and location-based reviews through one contract.
We are built for production systems, not demos:
- Official platform APIs and approved OAuth scopes only (no scraping, no risky unofficial automation)
- Reliability-first execution with retries, per-platform states, and clear failure reporting
- Infrastructure and compliance posture designed for serious teams
- Human support that helps you ship and keep pipelines healthy
## What Postproxy Does
Postproxy replaces per-platform logic with one API layer that handles:
- Platform-specific endpoints, media rules, and validation
- OAuth token handling and refresh
- Publish execution, retries, and per-platform status visibility
- Engagement workflows (comments, DMs, reviews)
Integrate once, keep one payload shape, and let Postproxy absorb platform differences.
For AI agent pipelines, Postproxy provides a native MCP server with tools for the full social workflow — publishing, comments, DMs, queues, and stats — so agents can execute end-to-end without building per-platform integrations.
## Reliability, Trust & Official APIs
- Infrastructure: European hosting and operations
- Security: encryption in transit/at rest, strict access controls
- Compliance: GDPR-compliant; SOC 2 Type II audit in progress — certification expected in 2026
- Officialness: only official APIs and approved auth flows
- Support: real people who know the product, across all plans
## How It Works
1. Create account and API key
2. Use sandbox mode to develop and test without real accounts or burned quota (included on all plans)
3. Connect social profiles in profile groups
4. Send posts, comments, DMs, and review replies via API
5. Track outcomes via statuses and webhooks
## Core Concepts
**Profile** - Connected social account (or account container) on a platform.
**Profile Group** - Logical workspace for profiles, credentials, and access scope.
**Post** - Content unit published to one or more profiles.
**Comment** - Engagement object on a post (or profile-scoped review for Google Business).
**Chat / Message** - 1:1 direct messaging entities (DM conversation and messages).
**Queue** - Recurring publishing schedule with timeslots, priorities, and jitter.
**Placement** - Platform destination target (for example Facebook Page, LinkedIn org, Pinterest board, Google location).
## Supported Platforms
| Platform | Platform ID | Formats |
|----------|-------------|---------|
| Facebook | `facebook` | `post`, `reel`, `story` |
| Instagram | `instagram` | `post`, `reel`, `story` |
| TikTok | `tiktok` | `video`, `image` |
| LinkedIn | `linkedin` | `post` |
| YouTube | `youtube` | `post` |
| X (Twitter) | `twitter` | `post`, `poll` |
| Threads | `threads` | `post` |
| Pinterest | `pinterest` | `pin` |
| Bluesky | `bluesky` | `post` |
| Telegram | `telegram` | `post` (channel) |
| Google Business | `google_business` | `standard`, `event`, `offer`, `photo` |
## Onboarding (self-serve, agent-friendly)
- **Free start**: 10 posts free, no credit card required — https://app.postproxy.dev/users/sign_up
- **Self-serve API keys**: generated in the app under Settings → API Keys, no sales contact needed
- **Sandbox mode**: included on all plans — develop and test without real social accounts or burned platform quota
- **Zero-auth try-it endpoint**: the content calendar API needs no key at all:
```bash
curl "https://api.postproxy.dev/api/calendar?country=US"
```
## Authentication
All requests use Bearer auth:
```
Authorization: Bearer YOUR_API_KEY
```
API key types:
- Full Access - all profile groups + profile-group management
- Profile Group Scoped - only one profile group
Profile group context can come from:
1. `?profile_group_id=<id>`
2. key scope
3. default group (full-access keys)
## Quickstart
### List profiles
```bash
curl -X GET "https://api.postproxy.dev/api/profiles" -H "Authorization: Bearer YOUR_API_KEY"
```
### Create post
```bash
curl -X POST "https://api.postproxy.dev/api/posts" -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{
"post": {"body": "Hello world"},
"profiles": ["facebook", "instagram"],
"media": ["https://example.com/image.jpg"]
}'
```
## Engagement: Comments, DMs & Reviews
Publishing is only the first half of the social workflow. Postproxy covers the full lifecycle — every inbound signal you need to act on is readable and writable through the same API.
### Comments (post-level)
Available on Instagram, Facebook, Threads, and Bluesky (YouTube and LinkedIn coming soon). For each platform you can list all comments on a post, reply, delete, hide/unhide, and like/unlike where supported. Write operations are async and return a status (`pending` → `published` / `failed`). Webhooks fire on each state change.
Key use cases:
- Automated comment moderation: filter toxic or spam comments and hide them without manual review
- AI-generated replies: read comments, generate responses, post them back with `POST /api/posts/:post_id/comments`
- Private replies: escalate a public Facebook or Instagram comment to a private DM thread via `POST /api/posts/:post_id/comments/:id/private_reply`
### Direct Messages
DMs are supported on Facebook Messenger, Instagram, Telegram, and Bluesky. You can list chats, find or create a chat by user, send and edit messages, react, and archive. Inbound messages arrive via webhooks (`message.received`).
Important: Facebook and Instagram operate inside a **24-hour messaging window** — you can only initiate outbound messages within 24h of the last inbound message from the user. Telegram and Bluesky have no such window (Telegram requires the user to DM the bot first).
Advanced capabilities:
- **Instagram ice breakers**: set suggested opening questions shown when a user opens a new DM thread (`GET/POST/DELETE /api/profiles/:id/ice_breakers`)
- **ig.me / m.me referrals**: link attribution that opens a 24h window alongside a campaign click — `referral.received` webhook
- **Telegram outbound edit**: update a sent message after delivery (`PATCH /api/messages/:id`)
Key use cases:
- Customer support inbox automation: route inbound DMs by intent, auto-reply or escalate to a human queue
- Campaign response handling: attribute inbound DMs to a referral source, trigger a personalized reply sequence
- Notification bots: send proactive messages via Telegram to users who have already started a conversation
### Google Business Reviews (Profile Comments)
Reviews belong to a location, not a post. Postproxy syncs incoming reviews twice daily (06:00 and 18:00 UTC) and exposes them under `GET /api/profiles/:profile_id/comments`. You can reply and delete your own replies. Useful for automating review response at scale across multiple Business Profile locations.
### Webhook events for engagement
All engagement events are delivered as HMAC-signed webhook payloads. Subscribe to `*` for all events or specific types:
- Post comments: `comment.created`, `comment.failed`, `comment.failed_waiting_for_retry`, `comment.delivery_unconfirmed`, `comment.edited`, `comment.edit_failed`
- Profile comments (reviews): `profile_comment.created`, `profile_comment.failed`, `profile_comment.failed_waiting_for_retry`
- DMs: `message.received`, `message.sent`, `message.delivered`, `message.read`, `message.edited`, `message.deleted`, `message.failed`, `message.failed_waiting_for_retry`
- DM extras: `reaction.received`, `referral.received`
## API Reference
Base URL: `https://api.postproxy.dev`
### Response Format
Single resource:
```json
{ "id": "abc123", "name": "My Resource" }
```
Collection:
```json
{ "total": 120, "page": 1, "per_page": 10, "data": [] }
```
### Common Errors
| Code | Response shape |
|------|----------------|
| `400` | `{"status":400,"error":"Bad Request","message":"..."}` |
| `401` | `{"error":"Invalid API key"}` |
| `404` | `{"error":"Not found"}` |
| `405` | `{"error":"Unsupported method for <platform>"}` |
| `422` | `{"error":"..."}` or `{"errors":["..."]}` |
### Pagination
| Parameter | Type | Default | Notes |
|-----------|------|---------|-------|
| `page` | integer | `1` | 1-based; passing `0` returns page `1` |
| `per_page` | integer | `10` | |
## Posts API
| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/posts` | List posts |
| `GET` | `/api/posts/:id` | Get post |
| `GET` | `/api/posts/stats` | Post stats snapshots |
| `POST` | `/api/posts` | Create post |
| `PATCH` | `/api/posts/:id` | Update post |
| `POST` | `/api/posts/:id/publish` | Publish draft |
| `POST` | `/api/posts/:id/delete_on_platform` | Delete on selected platform(s) |
| `DELETE` | `/api/posts/:id` | Delete from Postproxy DB |
Create/update highlights:
- `profiles`: profile ids or platform ids
- `media`: URL, multipart file, base64/data-uri shapes
- `platforms`: per-platform params
- `thread`: follow-up posts for chains (X, Threads, Bluesky)
- `queue_id` + `queue_priority`: queue scheduling
- drafts, scheduling, and profile-group scoping supported
Threading:
- Supported on X, Threads, Bluesky
- Children publish sequentially inside each platform chain
- Chains run independently per platform
X Polls:
- `platforms.twitter.format = "poll"`
- `poll_options`: 2-4 options (max 25 chars each)
- `poll_duration_minutes`: 5..10080
- Polls cannot include media and cannot be threaded
Delete-on-platform support:
- Facebook, Threads, X, LinkedIn, Pinterest, YouTube
Post statuses:
- Post-level: `draft`, `processing`, `processed`, `scheduled`
- Platform-level: `processing`, `published`, `failed`, `failed_waiting_for_retry`, `deleted`
## Comments API (post-level)
| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/posts/:post_id/comments` | List comments |
| `GET` | `/api/posts/:post_id/comments/:id` | Get comment |
| `POST` | `/api/posts/:post_id/comments` | Create comment/reply |
| `DELETE` | `/api/posts/:post_id/comments/:id` | Delete comment |
| `POST` | `/api/posts/:post_id/comments/:id/hide` | Hide comment |
| `POST` | `/api/posts/:post_id/comments/:id/unhide` | Unhide comment |
| `POST` | `/api/posts/:post_id/comments/:id/like` | Like comment |
| `POST` | `/api/posts/:post_id/comments/:id/unlike` | Unlike comment |
All endpoints require `profile_id` query parameter.
Support matrix:
| Action | Instagram | Facebook | Threads | Bluesky | YouTube | LinkedIn |
|--------|-----------|----------|---------|---------|---------|----------|
| List | Yes | Yes | Yes | Yes | Coming soon | Coming soon |
| Reply | Yes | Yes | Yes | No | Coming soon | Coming soon |
| Delete | Yes | Yes | No | No | Coming soon | Coming soon |
| Hide/Unhide | Yes | Yes | Yes | No | Coming soon | Coming soon |
| Like/Unlike | No | Yes | No | No | Coming soon | Coming soon |
Notes:
- Unsupported actions return `405`
- Write operations are async (`pending` -> `published`/`failed`)
- Google Business reviews are profile-scoped, use Profile Comments API
## Direct Messages API
DMs are supported on Facebook Messenger, Instagram, Telegram, and Bluesky.
| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/profiles/:profile_id/chats` | List chats |
| `POST` | `/api/profiles/:profile_id/chats` | Find/create chat |
| `GET` | `/api/chats/:id` | Get chat |
| `GET` | `/api/chats/:chat_id/messages` | List messages |
| `POST` | `/api/chats/:chat_id/messages` | Send message |
| `GET` | `/api/messages/:id` | Get message |
| `PATCH` | `/api/messages/:id` | Edit outbound message (Telegram) |
| `POST` | `/api/messages/:id/react` | React to message (FB/IG) |
| `DELETE` | `/api/messages/:id/unreact` | Remove reaction |
| `POST` | `/api/chats/:id/archive` | Archive chat (Bluesky) |
| `DELETE` | `/api/chats/:id/archive` | Unarchive chat (Bluesky) |
| `POST` | `/api/posts/:post_id/comments/:id/private_reply` | DM comment author (FB/IG) |
| `GET/POST/DELETE` | `/api/profiles/:id/ice_breakers` | Instagram ice breakers |
Capability matrix:
| Capability | Facebook | Instagram | Telegram | Bluesky |
|------------|----------|-----------|----------|---------|
| Text send/receive | Yes | Yes | Yes | Yes |
| Attachments | Yes | Yes | Yes | No |
| Reactions | Yes | Yes | No | No |
| Edit outbound | No | No | Yes | No |
| Delivery/read receipts | Yes | Yes | No | No |
| Archive chat | No | No | No | Yes |
| Private reply to comment | Yes | Yes | No | No |
| Ice breakers | No | Yes | No | No |
| ig.me / m.me referrals | Yes | Yes | No | No |
Messaging window:
- Meta (Facebook/Instagram): 24h from last inbound user message
- ig.me/m.me referral also opens 24h window
- Telegram: no 24h window, but user must DM bot first
- Bluesky: no 24h window; recipient DM preferences apply
Message statuses:
- outbound: `pending`, `published`, `failed_waiting_for_retry`, `failed`
- inbound: `received`
Send message example:
```bash
curl -X POST "https://api.postproxy.dev/api/chats/CHAT_ID/messages" -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"body":"Thanks for reaching out"}'
```
## Profile Comments API (Google Business reviews)
Profile comments are comments that belong to a profile/location (not a post). Currently this API is for Google Business reviews.
| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/profiles/:profile_id/comments` | List profile comments |
| `GET` | `/api/profiles/:profile_id/comments/:id` | Get profile comment |
| `POST` | `/api/profiles/:profile_id/comments` | Reply to review |
| `DELETE` | `/api/profiles/:profile_id/comments/:id` | Delete your reply |
Key behaviors:
- `placement_id` filters by location (`accounts/X/locations/Y`)
- Multi-location accounts without `placement_id` return mixed location reviews
- Top-level reviews are synced from Google; API writes are replies only (`parent_id` required)
- Sync runs twice daily (06:00 and 18:00 UTC)
- `permalink` points to location reviews page
## Queues API
| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/post_queues` | List queues |
| `GET` | `/api/post_queues/:id` | Get queue |
| `GET` | `/api/post_queues/:id/next_slot` | Next available slot |
| `POST` | `/api/post_queues` | Create queue |
| `PATCH` | `/api/post_queues/:id` | Update queue |
| `DELETE` | `/api/post_queues/:id` | Delete queue |
Queue concepts:
- Timeslots: weekly `day` (0-6) + `time` (`HH:MM`) in queue timezone
- Priority: `high`, `medium`, `low`
- Jitter: random shift 0-60 min
- Pause via `enabled: false`
- Rearrangement happens automatically when inputs change
To queue a post, pass `queue_id` and optional `queue_priority` in `POST /api/posts`.
## Profiles API
| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/profiles` | List profiles |
| `GET` | `/api/profiles/:id` | Get profile |
| `GET` | `/api/profiles/:id/placements` | List placements |
| `DELETE` | `/api/profiles/:id` | Disconnect profile |
Placements are relevant for platforms like Facebook pages, LinkedIn organizations, Pinterest boards, and Google Business locations.
## Profile Groups API
| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/profile_groups` | List profile groups |
| `GET` | `/api/profile_groups/:id` | Get profile group |
| `POST` | `/api/profile_groups` | Create profile group |
| `DELETE` | `/api/profile_groups/:id` | Delete profile group |
| `POST` | `/api/profile_groups/:id/initialize_connection` | Create OAuth connect URL |
## Webhooks
Subscribe to all events (`*`) or specific event types.
Event types:
- Posts: `post.processed`, `post.imported`, `platform_post.published`, `platform_post.failed`, `platform_post.failed_waiting_for_retry`, `platform_post.edited`, `platform_post.edit_failed`, `platform_post.insights`
- Post comments: `comment.created`, `comment.failed`, `comment.failed_waiting_for_retry`, `comment.delivery_unconfirmed`, `comment.edited`, `comment.edit_failed`
- Profile comments: `profile_comment.created`, `profile_comment.failed`, `profile_comment.failed_waiting_for_retry`
- DMs: `message.received`, `message.sent`, `message.delivered`, `message.read`, `message.edited`, `message.deleted`, `message.failed_waiting_for_retry`, `message.failed`
- DM reactions/referrals: `reaction.received`, `referral.received`
## Platform-Specific Parameters (high-level)
### Facebook (`facebook`)
- Formats: `post`, `reel`, `story`
- Common params: `format`, `first_comment`, `page_id`
- Comments + DMs supported
### Instagram (`instagram`)
- Formats: `post`, `reel`, `story`
- Reel params include `cover_url`, `thumb_offset`, collaborators, optional trial strategy
- Comments + DMs + ice breakers + private reply supported
### TikTok (`tiktok`)
- Formats: `video`, `image`
- Params include privacy and interaction toggles (`disable_comment`, `disable_duet`, `disable_stitch`)
- No comments API, no DMs API
### LinkedIn (`linkedin`)
- Format: `post`
- Param: `organization_id`
- Comments support coming soon; no DMs API
### YouTube (`youtube`)
- Format: `post` (channel video)
- Params: `title`, `privacy_status`, optional `cover_url`
### X (Twitter) (`twitter`)
- Formats: `post`, `poll`
- Poll params: `poll_options`, `poll_duration_minutes`
- Supports post chains (threads)
### Threads (`threads`)
- Format: `post`
- Supports post chains
- Post comments supported (list/reply/hide)
### Pinterest (`pinterest`)
- Format: `pin`
- Params: `title`, `board_id` (required), `destination_link`, video cover params
### Bluesky (`bluesky`)
- Format: `post`
- Supports post chains and DM text
- Comments are list-only (read), DMs are text-only, archive/unarchive chat supported
### Telegram (`telegram`)
- Format: `post` (channel publishing)
- Params: `parse_mode`, `disable_link_preview`, `disable_notification`
- DMs supported; supports `reply_markup` and outbound edit via DM API
### Google Business (`google_business`)
- Formats: `standard`, `event`, `offer`, `photo`
- Key params: `location_id`, `cta_action_type`, `cta_url`, event/offer date fields
- Reviews and replies handled via Profile Comments API
## Calendar API (public, no auth)
`GET /api/calendar` exposes social dates (holidays, awareness, sensitive/no-post windows) with filters for category, type, country, tags, month, and date range.
## Automation & Workflow Integrations
Postproxy is designed for automation-first teams. Use one reliable execution layer behind your orchestrators and agents.
Available integrations:
- MCP - Native MCP server for AI agents (see below)
- OpenClaw - ClawHub skill for personal AI assistant workflows
- n8n - Verified node
- Make - Official app
- Zapier - Verified app
Typical scenarios:
- CMS -> social auto-publishing
- AI-generated content -> human approval -> publish
- Multi-brand routing and per-account outcomes
- Event-driven publishing from product/backend events
- Support and engagement automations (comments, DMs, reviews)
## MCP Server (AI Agents)
Postproxy exposes the **full social workflow as native MCP capabilities** — not just publishing. Agents get everything they need to run end-to-end pipelines: publish content, manage queues, moderate and reply to comments, read and send DMs, check stats, and track outcomes — all through one stable tool surface.
Works with Claude Code, Cursor, and any MCP-compatible client. Two deployment options:
- **Hosted remote MCP** (zero install): `https://mcp.postproxy.dev/mcp?api_key=YOUR_KEY` (or `X-Postproxy-API-Key` header)
- **Local npm package**: `npm install -g postproxy-mcp` with stdio transport
Why MCP + Postproxy for agent pipelines:
- One contract f
