Create Post

{
    "workspace_id": 12,
    "labels": [
        5
    ],
    "content": [
        {
            "text": "Check out our new reel!",
            "media": [
                1842
            ],
            "cover_image": {
                "thumbnail": 1843
            }
        }
    ],
    "schedule_type": "schedule",
    "schedule_for": {
        "date": "2025-07-05",
        "time": "23:00",
        "timezone": "Africa/Addis_Ababa"
    },
    "accounts": [
        {
            "id": 136,
            "settings": {
                "for_super_followers_only": false,
                "reply_settings": "everyone",
                "quote_tweet_id": null,
                "reply": {
                    "in_reply_to_tweet_id": null
                },
                "community_id": null,
                "share_with_followers": true,
                "text": null
            }
        }
    ]
}

{ 
  "id": 749,
  "content": [
      {
          "text": "Post Once. Publissh everywhere",
          "media": [
              {
                  "id": 1672,
                  "name": "banner.png",
                  "url": "https://postsyncer.com/images/og/banner.png?v2",
                  "type": "image/png",
                  "size": 210537
              }
          ]
      }
  ],
  "status": "SCHEDULED",
  "posted_on": [],
  "scheduled_at": "2025-07-05 23:00 PM",
  "repeatable": null,
  "repeatable_times": null,
  "repeatable_gap": null,
  "repeatable_gap_unit": null,
  "remaining_posts": null,
  "created_at": "2025-07-05 17:04 PM",
  "updated_at": "2025-07-05 17:04 PM",
  "workspace": {
      "id": 12,
      "name": "abdulmejidshemsuawel",
      "slug": "abdulmejidshemsuawel",
      "type": "PERSONAL",
      "logo": null,
      "timezone": "Africa/Addis_Ababa",
      "language": "en"
  },
  "labels": [
      {
          "id": 5,
          "name": "ol pasdm",
          "color": "#bf3434"
      }
  ],
  "platforms": [
      {
          "platform": "twitter",
          "posted_on": [],
          "status": "PENDING",
          "settings": {
              "for_super_followers_only": false,
              "reply_settings": "everyone",
              "quote_tweet_id": null,
              "reply": {
                  "in_reply_to_tweet_id": null
              },
              "community_id": null,
              "share_with_followers": true,
              "text": "",
              "poll": {
                  "enabled": false,
                  "duration_minutes": null,
                  "reply_settings": "everyone",
                  "options": null
              }
          }
      }
  ],
  "auto_plug": null 
}

POST

posts

{
    "workspace_id": 12,
    "labels": [
        5
    ],
    "content": [
        {
            "text": "Check out our new reel!",
            "media": [
                1842
            ],
            "cover_image": {
                "thumbnail": 1843
            }
        }
    ],
    "schedule_type": "schedule",
    "schedule_for": {
        "date": "2025-07-05",
        "time": "23:00",
        "timezone": "Africa/Addis_Ababa"
    },
    "accounts": [
        {
            "id": 136,
            "settings": {
                "for_super_followers_only": false,
                "reply_settings": "everyone",
                "quote_tweet_id": null,
                "reply": {
                    "in_reply_to_tweet_id": null
                },
                "community_id": null,
                "share_with_followers": true,
                "text": null
            }
        }
    ]
}

{ 
  "id": 749,
  "content": [
      {
          "text": "Post Once. Publissh everywhere",
          "media": [
              {
                  "id": 1672,
                  "name": "banner.png",
                  "url": "https://postsyncer.com/images/og/banner.png?v2",
                  "type": "image/png",
                  "size": 210537
              }
          ]
      }
  ],
  "status": "SCHEDULED",
  "posted_on": [],
  "scheduled_at": "2025-07-05 23:00 PM",
  "repeatable": null,
  "repeatable_times": null,
  "repeatable_gap": null,
  "repeatable_gap_unit": null,
  "remaining_posts": null,
  "created_at": "2025-07-05 17:04 PM",
  "updated_at": "2025-07-05 17:04 PM",
  "workspace": {
      "id": 12,
      "name": "abdulmejidshemsuawel",
      "slug": "abdulmejidshemsuawel",
      "type": "PERSONAL",
      "logo": null,
      "timezone": "Africa/Addis_Ababa",
      "language": "en"
  },
  "labels": [
      {
          "id": 5,
          "name": "ol pasdm",
          "color": "#bf3434"
      }
  ],
  "platforms": [
      {
          "platform": "twitter",
          "posted_on": [],
          "status": "PENDING",
          "settings": {
              "for_super_followers_only": false,
              "reply_settings": "everyone",
              "quote_tweet_id": null,
              "reply": {
                  "in_reply_to_tweet_id": null
              },
              "community_id": null,
              "share_with_followers": true,
              "text": "",
              "poll": {
                  "enabled": false,
                  "duration_minutes": null,
                  "reply_settings": "everyone",
                  "options": null
              }
          }
      }
  ],
  "auto_plug": null 
}

Creates a new post that can be scheduled or published immediately across multiple social media platforms. The post can include text content, media attachments, and platform-specific settings.

Request

workspace_id

integer

required

The ID of the workspace where the post will be created

labels

string[]

Optional array of label IDs to apply to this post

content

object[]

required

Array of content objects (threads). Each object can contain text and media. At least one content item with text or media is required.

Show Content Object

text

string

The text content for this post

media

string[]

Attachments for this thread. Each item is either a string (public HTTPS URL to an image or video) or a (media library id from POST /media/upload/file or POST /media/upload/url, same workspace_id). You may mix URLs and ids in one array. See Media overview.

cover_image

object

Optional cover/thumbnail for video posts. Only the first content item’s cover_image is used when publishing. Which field you use depends on the target platform — see Platform requirements below.

Show Cover Image Object

thumbnail

string

Custom cover image upload — workspace media library id (image only) or public HTTPS URL to an image. Upload via POST /media/upload/file or POST /media/upload/url. Required for YouTube, Instagram, and Facebook video/Reels. Not used on TikTok.

video_cover_timestamp_ms

integer

Frame selection from the attached video — timestamp in milliseconds (e.g. 2500 = 2.5 seconds). TikTok only. Custom thumbnail upload is not supported on TikTok.

schedule_type

string

required

Type of scheduling. Must be one of: publish_now, schedule, draft

schedule_for

object

Optional scheduling object used when schedule_type is schedule. Provide {"date": "YYYY-MM-DD", "time": "HH:MM", "timezone": "..."} to schedule for a specific date/time, or omit/leave empty to auto-schedule to the next available time slot

Show Schedule Object

date

string

required

The date to schedule the post (YYYY-MM-DD format)

time

string

required

The time to schedule the post (HH:MM format in 24-hour)

timezone

string

Timezone for the scheduled time (defaults to workspace timezone)

repeatable

boolean

Whether the post should be repeated

repeatable_times

integer

Number of times to repeat the post. Required if repeatable is true.

repeatable_gap

integer

Time gap between repeats. Required if repeatable is true.

repeatable_gap_unit

string

The unit for the repeatable gap. Must be one of: minutes, hours, days, weeks, months. Required if repeatable is true.

repeatable_accounts

integer[]

Optional. Only when repeatable is true: account IDs (in this workspace_id) to limit repeat scheduling to those accounts. Omit or empty for default behavior. To turn off repeat scheduling, send repeatable: false on update post.

Auto plug, comment moderation, and contact collection each have a dedicated PATCH endpoint. Repeat scheduling uses repeatable / repeatable_accounts on create and update.

accounts

array

Array of account objects to publish to

Show Account Object

integer

required

The ID of the social media account

settings

object

Platform-specific settings for this post. Optional except for Pinterest which requires a board_id. The available settings depend on the platform:

Show Twitter/X Settings

for_super_followers_only

boolean

Whether to restrict the post to super followers only (default: false)

reply_settings

string

Who can reply to the post. Options: ‘everyone’, ‘following’, ‘mentioned_users’ (default: ‘everyone’)

quote_tweet_id

string

ID of the tweet to quote (optional)

object

Reply settings object with ‘in_reply_to_tweet_id’ (optional)

community_id

string

ID of the community to post to (optional)

Share community post with followers too.

text

string

Custom text content for Twitter (optional) - (This allows overriding the platform-specific text content)

poll

object

Poll settings with ‘enabled’, ‘duration_minutes’, ‘reply_settings’, and ‘options’ (optional)

Show Poll Settings

enabled

boolean

duration_minutes

string

reply_settings

string

everyone, following, mentionedUsers

options

array

Poll options, array of text

Show Instagram Settings

post_type

string

Type of post. Options: ‘REELS’, ‘STORIES’, ‘POST’ (default: ‘REELS’) (optional)

caption

string

Custom caption for Instagram (optional) - (This allows overriding the platform-specific text content)

Show Facebook Settings

post_type

string

Type of post. Options: ‘REELS’, ‘STORIES’, ‘POST’ (default: ‘REELS’) (optional)

title

string

Custom title for the Facebook post (optional) - (This allows overriding the platform-specific text content)

link

string

URL to attach to the post (optional)

Show LinkedIn Settings

visibility

string

Post visibility. Options: ‘PUBLIC’, ‘CONNECTIONS’, ‘LOGGED_IN’ (default: ‘PUBLIC’)

link

string

URL to attach to the post (optional)

title

string

Custom title for the LinkedIn post (optional) - (This allows overriding the platform-specific text content)

Show YouTube Settings

video_type

string

Type of video. Options: ‘video’, ‘short’ (default: ‘video’)

title

string

Video title (optional)

description

string

Video description (optional) - (This allows overriding the platform-specific text content)

privacyStatus

string

Privacy status. Options: ‘public’, ‘private’, ‘unlisted’ (default: ‘public’)

Response

integer

Unique identifier for the created post

content

array

Array of content objects with text, media, and optional cover_image. Platform cover requirements: TikTok — video_cover_timestamp_ms only; YouTube, Instagram, Facebook — thumbnail only.

status

string

Status of the post (draft, scheduled, published, failed)

posted_on

array

Array of posted timestamps in workspace timezone

scheduled_at

string

Scheduled date and time in workspace timezone

repeatable

boolean

Whether the post is set to repeat

repeatable_times

integer

Number of times the post will repeat

repeatable_gap

integer

Gap between repeats

repeatable_gap_unit

string

Unit for the repeat gap (hours, days, weeks, months)

remaining_posts

integer

Number of remaining posts in the repeat sequence

workspace

object

Information about the post’s workspace

labels

array

Array of labels attached to the post

platforms

array

Array of platform-specific post information

auto_plug

object | null

Auto plug configuration when enabled, or null when off. Update via Update post auto plug.

created_at

string

Creation timestamp in workspace timezone

updated_at

string

Last update timestamp in workspace timezone

{ 
  "id": 749,
  "content": [
      {
          "text": "Post Once. Publissh everywhere",
          "media": [
              {
                  "id": 1672,
                  "name": "banner.png",
                  "url": "https://postsyncer.com/images/og/banner.png?v2",
                  "type": "image/png",
                  "size": 210537
              }
          ]
      }
  ],
  "status": "SCHEDULED",
  "posted_on": [],
  "scheduled_at": "2025-07-05 23:00 PM",
  "repeatable": null,
  "repeatable_times": null,
  "repeatable_gap": null,
  "repeatable_gap_unit": null,
  "remaining_posts": null,
  "created_at": "2025-07-05 17:04 PM",
  "updated_at": "2025-07-05 17:04 PM",
  "workspace": {
      "id": 12,
      "name": "abdulmejidshemsuawel",
      "slug": "abdulmejidshemsuawel",
      "type": "PERSONAL",
      "logo": null,
      "timezone": "Africa/Addis_Ababa",
      "language": "en"
  },
  "labels": [
      {
          "id": 5,
          "name": "ol pasdm",
          "color": "#bf3434"
      }
  ],
  "platforms": [
      {
          "platform": "twitter",
          "posted_on": [],
          "status": "PENDING",
          "settings": {
              "for_super_followers_only": false,
              "reply_settings": "everyone",
              "quote_tweet_id": null,
              "reply": {
                  "in_reply_to_tweet_id": null
              },
              "community_id": null,
              "share_with_followers": true,
              "text": "",
              "poll": {
                  "enabled": false,
                  "duration_minutes": null,
                  "reply_settings": "everyone",
                  "options": null
              }
          }
      }
  ],
  "auto_plug": null 
}

Code Examples

curl -X POST "https://postsyncer.com/api/v1/posts" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": 12,
    "labels": [
      5
    ],
    "content": [
      {
        "text": "Post Once. Publissh everywhere",
        "media": [
          "https://postsyncer.com/images/og/banner.png?v2"
        ]
      }
    ],
    "schedule_type": "schedule",
    "schedule_for": {
      "date": "2025-07-05",
      "time": "23:00",
      "timezone": "Africa/Addis_Ababa"
    },
    "accounts": [
      {
        "id": 136,
        "settings": {
          "for_super_followers_only": false,
          "reply_settings": "everyone",
          "quote_tweet_id": null,
          "reply": {
            "in_reply_to_tweet_id": null
          },
          "community_id": null,
          "share_with_followers": true,
          "text": null
        }
      }
    ]
  }'

Platform-Specific Settings

Each social media platform supports different settings that allow you to customize how your post appears and behaves. These settings are specified in the settings object for each account in the accounts array.

Twitter/X Settings

for_super_followers_only: Restrict post visibility to super followers
reply_settings: Control who can reply (‘everyone’, ‘following’, ‘mentioned_users’)
quote_tweet_id: Quote an existing tweet
reply: Reply to a specific tweet
community_id: Post to a specific community
share_with_followers: Share community post with followers too
text: Override the main text content for Twitter
poll: Create a poll with options and duration

Instagram Settings

post_type: Choose between ‘REELS’, ‘STORIES’, or ‘POST’
caption: Custom caption with hashtags and mentions

Facebook Settings

title: Custom title for the post
link: Attach a URL to the post

LinkedIn Settings

visibility: Control post visibility (‘PUBLIC’, ‘CONNECTIONS’, ‘LOGGED_IN’)
link: Attach a URL to the post
title: Custom title for the post

YouTube Settings

video_type: Choose between ‘video’ or ‘short’
title: Video title
description: Video description
privacyStatus: Set privacy (‘public’, ‘private’, ‘unlisted’)
tags: Array of tags for better discoverability
embeddable: Allow video embedding
selfDeclaredMadeForKids: Mark as content for children
notifySubscribers: Send notifications to subscribers
category_id: YouTube category

TikTok Settings

privacy_level: Set video privacy (PUBLIC_TO_EVERYONE, MUTUAL_FOLLOW_FRIENDS, FOLLOWER_OF_CREATOR, SELF_ONLY)
title: Video title
description: Video description
disable_comment: Turn off comments
disable_duet: Disable duet feature
disable_stitch: Disable stitch feature
brand_content_toggle: Mark as brand content
brand_organic_toggle: Mark as organic brand content
is_aigc: Indicate AI-generated content
auto_add_music: Automatically add music
post_mode: Enum: DIRECT_POST (post directly) | MEDIA_UPLOAD (upload for user to finish in TikTok)

Pinterest Settings

board_id: Specify which board to pin to
link: Attach a URL to the pin
title: Pin title
description: Pin description
note: Additional pin notes
published: Publish immediately or save as draft

Threads Settings

title: Custom title for the post
link_attachment: Attach a URL to the post

Telegram Settings

title: Custom title for the message
disable_notification: Send silently
protect_content: Protect from forwarding

Bluesky Settings

title: Custom title for the post
website_card: Add a website card with URI, title, and description

Media Guidelines

Different social platforms have different requirements for media. PostSyncer will automatically process your media to meet platform requirements, but keep these limitations in mind:

Video cover images

Set content[0].cover_image when creating or updating a video post. Only the first content thread’s cover is applied when publishing.

Platform requirements for cover images

Platform	Cover method	API field
TikTok	Frame selection from video only	`video_cover_timestamp_ms`
YouTube	Custom thumbnail upload only	`thumbnail`
Instagram (Reels)	Custom thumbnail upload only	`thumbnail`
Facebook (Reels / video)	Custom thumbnail upload only	`thumbnail`

Do not send thumbnail for TikTok — use video_cover_timestamp_ms to pick a frame from the video. Do not send video_cover_timestamp_ms for YouTube, Instagram, or Facebook — upload a cover image and pass its library id (or a public image URL) in thumbnail.

TikTok example — frame at 2.5 seconds:

"content": [{
  "text": "New TikTok!",
  "media": [1842],
  "cover_image": {"video_cover_timestamp_ms": 2500}
}]

Instagram / Facebook / YouTube example — custom cover image:

"content": [{
  "text": "New reel!",
  "media": [1842],
  "cover_image": {"thumbnail": 1843}
}]

Typical workflow for custom thumbnails: upload the video → upload the cover image → create the post with both ids in content[0].

Platform	Max Images	Max Videos	Required Media	Max File Size
Twitter/X	4	1	No	5MB (img), 512MB (video)
Facebook	10	1	No	10MB (img), 4GB (video)
Instagram	10	1	Yes	8MB (img), 100MB (video)
TikTok	35	1	Yes	20MB (img), 4GB (video)
YouTube	0	1	Yes	N/A, 10GB (video)
Pinterest	5	1	Yes	20MB (img), 200MB (video)
Threads	10	10	No	8MB (img), 1GB (video)
Telegram	10	10	No	5MB (img), 20MB (video)
LinkedIn	9	1	No	5MB (img), 512MB (video)
Bluesky	4	1	No	1MB (img), 100MB (video)

Error Codes

400

Bad Request

Validation errors, invalid parameters, or invalid media URLs

401

Unauthorized

Missing or invalid API token

403

Forbidden

Token does not have ‘posts’ permission

404

Not Found

Workspace, label, or account not found

422

Unprocessable Entity

Validation errors in request data

List Posts

Get Post

​Create Post

​Request

​Response

​Code Examples

​Platform-Specific Settings

​Twitter/X Settings

​Instagram Settings

​Facebook Settings

​LinkedIn Settings

​YouTube Settings

​TikTok Settings

​Pinterest Settings

​Threads Settings

​Telegram Settings

​Bluesky Settings

​Media Guidelines

​Video cover images

​Platform requirements for cover images

​Error Codes

Create Post

Request

Response

Code Examples

Platform-Specific Settings

Twitter/X Settings

Instagram Settings

Facebook Settings

LinkedIn Settings

YouTube Settings

TikTok Settings

Pinterest Settings

Threads Settings

Telegram Settings

Bluesky Settings

Media Guidelines

Video cover images

Platform requirements for cover images

Error Codes