Posts API
Create, schedule, update, and delete social media posts across 7 platforms with a single API. Posts are the core resource in PostEverywhere — every post can target multiple accounts and each destination is tracked independently.
/posts
Create and schedule a post to one or more connected social media accounts. Omit scheduled_at to publish immediately, or provide a future datetime to schedule.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
content | string | Yes | The text content of your post. Platform character limits apply (e.g., 280 for X, 2,200 for Instagram). |
account_ids | int[] | Yes | Array of account IDs to publish to. Get these from GET /accounts. |
scheduled_at | string | No | ISO 8601 datetime. Omit to publish immediately. Must be in the future. |
timezone | string | No | IANA timezone (e.g., "America/New_York"). Defaults to UTC if omitted. |
media_ids | uuid[] | No | Array of media UUIDs from POST /media/upload. Attach images, videos, or documents. |
Example Request
curl -X POST https://app.posteverywhere.ai/api/v1/posts \
-H "Authorization: Bearer pe_live_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"content": "Just shipped our latest feature! Check it out at example.com",
"account_ids": [1, 4, 7],
"scheduled_at": "2026-03-15T14:00:00Z",
"timezone": "America/New_York",
"media_ids": ["a1b2c3d4-5678-9012-abcd-ef1234567890"]
}'Response — 201 Created
{
"data": {
"post_id": "post_8f3k2j1",
"status": "scheduled",
"scheduled_for": "2026-03-15T14:00:00Z",
"accounts_count": 3,
"message": "Post scheduled for 3 accounts"
},
"meta": {
"request_id": "req_abc123def456",
"timestamp": "2026-03-10T10:30:00Z"
}
}Immediate vs. scheduled: If you omit scheduled_at, the post begins publishing immediately and the response status will be "publishing" instead of "scheduled".
/posts
Retrieve a paginated list of posts with optional filtering by status and platform.
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
status | string | all | Filter by status: scheduled, published, or draft |
platform | string | all | Filter by platform: instagram, x, linkedin, facebook, tiktok, youtube, threads |
limit | integer | 20 | Number of posts to return. Range: 1–100. |
offset | integer | 0 | Number of posts to skip for pagination. |
Example Request
curl https://app.posteverywhere.ai/api/v1/posts?status=scheduled&limit=10 \
-H "Authorization: Bearer pe_live_your_key_here"Response — 200 OK
{
"data": [
{
"id": "post_8f3k2j1",
"content": "Just shipped our latest feature!",
"media": [],
"scheduled_for": "2026-03-15T14:00:00Z",
"timezone": "America/New_York",
"status": "scheduled",
"destinations": [
{ "id": "dest_001", "platform": "instagram", "status": "queued", "account_name": "@acme" },
{ "id": "dest_002", "platform": "linkedin", "status": "queued", "account_name": "Acme Inc." }
],
"created_at": "2026-03-10T10:30:00Z",
"updated_at": "2026-03-10T10:30:00Z"
}
],
"meta": {
"request_id": "req_xyz789",
"timestamp": "2026-03-10T11:00:00Z"
}
}/posts/{id}
Retrieve full details for a single post, including all platform destinations and their individual statuses.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
id | string | The post ID (e.g., post_8f3k2j1) |
Example Request
curl https://app.posteverywhere.ai/api/v1/posts/post_8f3k2j1 \
-H "Authorization: Bearer pe_live_your_key_here"Response — 200 OK
{
"data": {
"id": "post_8f3k2j1",
"content": "Just shipped our latest feature! Check it out at example.com",
"media": [
{ "id": "a1b2c3d4-5678-9012-abcd-ef1234567890", "type": "image", "url": "https://cdn.posteverywhere.ai/..." }
],
"scheduled_for": "2026-03-15T14:00:00Z",
"timezone": "America/New_York",
"status": "published",
"destinations": [
{
"id": "dest_001",
"platform": "instagram",
"status": "published",
"account_name": "@acme",
"account_id": 1,
"published_at": "2026-03-15T14:00:02Z",
"platform_post_id": "17895695668004550",
"error": null,
"attempts": 1
},
{
"id": "dest_002",
"platform": "linkedin",
"status": "published",
"account_name": "Acme Inc.",
"account_id": 4,
"published_at": "2026-03-15T14:00:03Z",
"platform_post_id": "urn:li:share:7123456789",
"error": null,
"attempts": 1
},
{
"id": "dest_003",
"platform": "x",
"status": "failed",
"account_name": "@acme_tweets",
"account_id": 7,
"published_at": null,
"platform_post_id": null,
"error": "Rate limit exceeded on platform",
"attempts": 3
}
],
"created_at": "2026-03-10T10:30:00Z",
"updated_at": "2026-03-15T14:00:03Z"
},
"meta": {
"request_id": "req_get456",
"timestamp": "2026-03-15T14:05:00Z"
}
}/posts/{id}
Update a post that has not yet been published. Only posts with status scheduled or draft can be updated.
Request Body
| Field | Type | Description |
|---|---|---|
content | string | Updated post content. |
scheduled_at | string | New scheduled datetime (ISO 8601). Must be in the future. |
timezone | string | IANA timezone string. |
account_ids | int[] | Replace the list of target accounts. |
media_ids | uuid[] | Replace the list of attached media. |
All fields are optional. Only include the fields you want to change.
Example Request
curl -X PATCH https://app.posteverywhere.ai/api/v1/posts/post_8f3k2j1 \
-H "Authorization: Bearer pe_live_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"content": "Updated: Launching our new feature tomorrow!",
"scheduled_at": "2026-03-16T10:00:00Z"
}'Response — 200 OK
{
"data": {
"id": "post_8f3k2j1",
"content": "Updated: Launching our new feature tomorrow!",
"scheduled_for": "2026-03-16T10:00:00Z",
"status": "scheduled",
"updated_at": "2026-03-10T12:00:00Z"
},
"meta": {
"request_id": "req_patch789",
"timestamp": "2026-03-10T12:00:00Z"
}
}Published posts cannot be updated. Attempting to PATCH a post with status "published" or "publishing" returns a 409 Conflict error.
/posts/{id}
Delete a post. Only posts with status scheduled or draft can be deleted. Published posts cannot be removed through the API because the content already exists on external platforms.
Example Request
curl -X DELETE https://app.posteverywhere.ai/api/v1/posts/post_8f3k2j1 \
-H "Authorization: Bearer pe_live_your_key_here"Response — 200 OK
{
"data": {
"id": "post_8f3k2j1",
"deleted": true
},
"meta": {
"request_id": "req_del012",
"timestamp": "2026-03-10T12:30:00Z"
}
}This action is irreversible. Deleting a post removes it and all associated destinations. Attempting to delete a published post returns a 409 Conflict error.
/posts/{id}/results
Get per-platform publishing results for a post. This endpoint returns detailed status for each destination, including published URLs, error messages, attempt counts, and retry scheduling.
Example Request
curl https://app.posteverywhere.ai/api/v1/posts/post_8f3k2j1/results \
-H "Authorization: Bearer pe_live_your_key_here"Response — 200 OK
{
"data": [
{
"id": "dest_001",
"platform": "instagram",
"status": "published",
"account_name": "@acme",
"account_id": 1,
"published_at": "2026-03-15T14:00:02Z",
"platform_post_id": "17895695668004550",
"platform_post_url": "https://www.instagram.com/p/ABC123/",
"error": null,
"attempts": 1,
"next_retry_at": null
},
{
"id": "dest_002",
"platform": "linkedin",
"status": "published",
"account_name": "Acme Inc.",
"account_id": 4,
"published_at": "2026-03-15T14:00:03Z",
"platform_post_id": "urn:li:share:7123456789",
"platform_post_url": "https://www.linkedin.com/feed/update/urn:li:share:7123456789",
"error": null,
"attempts": 1,
"next_retry_at": null
},
{
"id": "dest_003",
"platform": "x",
"status": "failed",
"account_name": "@acme_tweets",
"account_id": 7,
"published_at": null,
"platform_post_id": null,
"platform_post_url": null,
"error": "Rate limit exceeded on platform",
"attempts": 3,
"next_retry_at": "2026-03-15T14:15:00Z"
}
],
"meta": {
"request_id": "req_res345",
"timestamp": "2026-03-15T14:10:00Z"
}
}PostResult Fields
| Field | Type | Description |
|---|---|---|
id | string | Unique destination ID |
platform | string | Platform name (e.g., instagram, x, linkedin) |
status | string | One of: queued, publishing, published, failed |
platform_post_url | string | null | Direct URL to the published post on the platform |
error | string | null | Error message if publishing failed |
attempts | integer | Number of publishing attempts made |
next_retry_at | string | null | When the next automatic retry is scheduled (if applicable) |
/posts/{id}/retry
Retry publishing for all failed destinations of a post. Only destinations with status failed are retried — already-published destinations are not affected.
Example Request
curl -X POST https://app.posteverywhere.ai/api/v1/posts/post_8f3k2j1/retry \
-H "Authorization: Bearer pe_live_your_key_here"Response — 200 OK
{
"data": {
"retried_count": 1,
"destinations": [
{
"id": "dest_003",
"platform": "x",
"new_status": "queued"
}
]
},
"meta": {
"request_id": "req_retry678",
"timestamp": "2026-03-15T14:20:00Z"
}
}Tip: If retried_count is 0, there were no failed destinations to retry. Check GET /posts/{id}/results first to confirm which destinations need retrying.
PostDestination Status Lifecycle
Each post creates one PostDestination per target account. Destinations progress through a status lifecycle independently, so one platform can succeed while another fails.
Post is waiting to be published. This is the initial state for scheduled posts.
Actively being sent to the platform. Usually lasts a few seconds.
Successfully published. The platform_post_url is now available.
Publishing failed after all retry attempts. Use POST /retry to try again.
PostDestination Fields
| Field | Type | Description |
|---|---|---|
id | string | Unique destination identifier |
platform | enum | x, instagram, facebook, linkedin, youtube, tiktok, threads |
status | enum | queued, publishing, published, failed |
account_name | string | Display name of the connected account |
account_id | integer | ID of the connected account |
published_at | string | null | ISO 8601 timestamp when published (null if not yet published) |
platform_post_id | string | null | Platform-native post ID (e.g., tweet ID, LinkedIn URN) |
error | string | null | Error message if publishing failed |
attempts | integer | Total number of publishing attempts |
Start publishing with the API
Get your API key and create your first post in under 5 minutes. API access is included on all plans from $19/mo.