Skip to main content
POST

Create Post

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

integer
required
The ID of the workspace where the post will be created
string[]
Optional array of label IDs to apply to this post
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.
string
required
Type of scheduling. Must be one of: publish_now, schedule, draft
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
boolean
Whether the post should be repeated
integer
Number of times to repeat the post. Required if repeatable is true.
integer
Time gap between repeats. Required if repeatable is true.
string
The unit for the repeatable gap. Must be one of: minutes, hours, days, weeks, months. Required if repeatable is true.
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.
array
Array of account objects to publish to

Response

integer
Unique identifier for the created post
array
Array of content objects with text, media, optional cover_image, and optional first-comment fields (is_first_comment, first_comment_delay). Platform cover requirements: TikTok - video_cover_timestamp_ms only; YouTube, Instagram, Facebook - thumbnail only.
string
Status of the post (draft, scheduled, published, failed)
array
Array of posted timestamps in workspace timezone
string
Scheduled date and time in workspace timezone
boolean
Whether the post is set to repeat
integer
Number of times the post will repeat
integer
Gap between repeats
string
Unit for the repeat gap (hours, days, weeks, months)
integer
Number of remaining posts in the repeat sequence
object
Information about the post’s workspace
array
Array of labels attached to the post
array
Array of platform-specific post information
object | null
Auto plug configuration when enabled, or null when off. Update via Update post auto plug.
string
Creation timestamp in workspace timezone
string
Last update timestamp in workspace timezone

Code Examples

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:

First comments

To schedule a first comment (hashtags, link, CTA) the same way the composer does, add a second content item with is_first_comment: true. On Instagram, Facebook, LinkedIn, and YouTube, that item is excluded from the main caption and posted as a comment after publish.
Supported first-comment platforms only: Instagram, Facebook, LinkedIn, and YouTube. Other platforms do not schedule a first comment from this flag.Multi-platform posts: If the same post also targets accounts that do not support first comments (for example TikTok or Threads), the is_first_comment item is still part of content, but those platforms handle it differently — TikTok may fold the text into the caption; Threads / X may treat extra content items as a thread. Put anything that must appear on every platform (links, CTAs) in the main caption, or wait for per-platform content if you need different copy per network.
On X/Twitter, content items are published as a native thread. Do not set is_first_comment for Twitter posts — use a separate comment via POST /comments after publish if you need a reply.

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

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:
Instagram / Facebook / YouTube example - custom cover image:
Typical workflow for custom thumbnails: upload the video → upload the cover image → create the post with both ids in content[0].

Error Codes

Bad Request
Validation errors, invalid parameters, or invalid media URLs
Unauthorized
Missing or invalid API token
Forbidden
Token does not have ‘posts’ permission
Not Found
Workspace, label, or account not found
Unprocessable Entity
Validation errors in request data