PostPlain API
PostPlain Agent-Native Social Media Scheduling API. Schedule posts to X, LinkedIn, Threads, and Facebook. Authenticate with a Bearer token using your mp_ prefixed API key.
Base URL: https://postplain.com/api/v1
Authentication: Include your API key as a Bearer token in the Authorization header.
Authorization: Bearer mp_your_api_key
Machine-readable formats:
openapi.json |
llms.txt (plain text for LLMs)
Account
GET
/accounts
List connected accounts
Returns all social media accounts connected to your team, including platform,
username, character limits, and connection timestamps.
POST
/accounts/connect/{platform}
Connect an account
Initiate an OAuth connection for a social platform. Returns a URL that a human
must visit to complete the OAuth flow. Supported platforms: x, linkedin, threads, facebook.
Parameters
| Name | In | Type | Required |
|---|
platform |
path |
string |
required |
DELETE
/accounts/{account}
Disconnect an account
Remove a connected social media account from your team. This is a soft delete;
previously published posts are not affected.
Parameters
| Name | In | Type | Required |
|---|
account |
path |
integer |
required |
Health
GET
/health
Health check
Returns the current health status of the API. This endpoint is unauthenticated
and can be used to verify connectivity before making authenticated requests.
Limits
GET
/limits
Get plan limits
Returns your team's current plan details, post usage, rate limits,
connected account count, and per-platform character constraints.
Use this before scheduling to check remaining quota.
Post
POST
/posts/schedule
Schedule a post
Schedule a post to one or more connected social accounts. If `scheduled_at` is omitted,
the post begins publishing in the background immediately after creation.
Supports idempotency keys to prevent duplicate posts.
Request body
| Field | Type | Required |
|---|
text |
string |
required |
scheduled_at |
string|null |
optional |
idempotency_key |
string|null |
optional |
account_ids |
array<integer> |
required |
media_urls |
array|null<string> |
optional |
platform_overrides |
object |
optional |
POST
/posts/bulk-schedule
Bulk schedule posts
Schedule up to 50 posts in a single request. Each post is processed independently;
failures for individual posts do not affect others. Returns separate arrays
of scheduled and failed posts.
Request body
| Field | Type | Required |
|---|
posts |
array<object> |
required |
GET
/posts/{post}
Get a post
Retrieve full details of a specific post, including per-platform publishing status,
platform post IDs, and timestamps.
Parameters
| Name | In | Type | Required |
|---|
post |
path |
integer |
required |
DELETE
/posts/{post}
Cancel a scheduled post
Cancel a post that has not yet been published. Only posts with status `scheduled`
can be cancelled. Already published or failed posts cannot be cancelled.
Parameters
| Name | In | Type | Required |
|---|
post |
path |
integer |
required |
GET
/posts/{post}/analytics
Get post analytics
Retrieve engagement analytics for a published post, broken down by platform.
Includes impressions, likes, comments, shares, and clicks.
Parameters
| Name | In | Type | Required |
|---|
post |
path |
integer |
required |
GET
/posts
List posts
Returns a paginated list of posts. Filter by status (scheduled, publishing, published,
failed, cancelled),
platform (x, linkedin, threads, facebook, bluesky), or date range (from/to as ISO 8601).
Parameters
| Name | In | Type | Required |
|---|
status |
query |
string |
optional |
platform |
query |
string |
optional |
from |
query |
string |
optional |
to |
query |
string |
optional |
per_page |
query |
string |
optional |
Webhook
POST
/webhooks
Create a webhook
Register a URL to receive POST notifications for specified events.
Returns a signing secret (whsec_ prefixed) for verifying webhook payloads.
Available events: post.published, post.failed, account.connected, account.disconnected.
All webhook payloads follow a standard envelope: `{"event": "post.published", "timestamp": "2026-04-01T09:00:05Z", "data": {...}}`.
See the WebhookPayload_PostPublished, WebhookPayload_PostFailed, WebhookPayload_AccountConnected,
and WebhookPayload_AccountDisconnected component schemas for full payload details.
Request body
| Field | Type | Required |
|---|
url |
string |
required |
events |
array<string> |
required |
GET
/webhooks
List webhooks
Returns all webhook subscriptions for your team.
PUT
/webhooks/{webhook}
Update a webhook
Modify a webhook's URL, events, or active status. Only provided fields are updated.
Parameters
| Name | In | Type | Required |
|---|
webhook |
path |
integer |
required |
Request body
| Field | Type | Required |
|---|
url |
string |
optional |
is_active |
boolean |
optional |
events |
array<string> |
optional |
DELETE
/webhooks/{webhook}
Delete a webhook
Permanently remove a webhook subscription. No further events will be delivered to this URL.
Parameters
| Name | In | Type | Required |
|---|
webhook |
path |
integer |
required |