> ## Documentation Index
> Fetch the complete documentation index at: https://docs.postsyncer.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Post
> Create a new social media post with content, media, and scheduling options
## 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
The ID of the workspace where the post will be created
Optional array of label IDs to apply to this post
Array of content objects (threads). Each object can contain text and media. At least one content item with text or media is required.
The text content for this post
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`](/api-reference/media/upload-file) or [`POST /media/upload/url`](/api-reference/media/upload-url), same `workspace_id`). You may mix URLs and ids in one array. See [Media overview](/api-reference/media/overview).
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](#platform-requirements-for-cover-images) below.
**Custom cover image upload** - workspace media library **id** (image only) or public **HTTPS URL** to an image. Upload via [`POST /media/upload/file`](/api-reference/media/upload-file) or [`POST /media/upload/url`](/api-reference/media/upload-url). **Required for YouTube, Instagram, and Facebook video/Reels.** Not used on TikTok.
**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.
When `true`, this content item is **not** part of the main post body on platforms that support first comments. After the post publishes successfully, PostSyncer posts this text (and optional media) as the first comment on **Instagram, Facebook, LinkedIn, and YouTube**. Only one content item may set this. You must still include at least one non-first-comment content item for the main post. On other platforms in the same post (e.g. TikTok, Threads), this flag does not schedule a first comment — see [First comments](#first-comments).
Minutes to wait after publish before posting the first comment. Defaults to `1` when `is_first_comment` is `true`. Max `10080` (7 days).
Type of scheduling. Must be one of:
publish\_now, schedule, draft
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
The date to schedule the post (YYYY-MM-DD format)
The time to schedule the post (HH:MM format in 24-hour)
Timezone for the scheduled time (defaults to workspace timezone)
Whether the post should be repeated
Number of times to repeat the post. Required if repeatable is true.
Time gap between repeats. Required if repeatable is true.
The unit for the repeatable gap. Must be one of: `minutes`, `hours`, `days`, `weeks`, `months`. Required if repeatable is true.
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](/api-reference/posts/update).
**[Auto plug](/api-reference/posts/auto-plug)**, **[comment moderation](/api-reference/posts/comment-moderation)**, and **[contact collection](/api-reference/posts/contact-collection)** each have a dedicated `PATCH` endpoint. Repeat scheduling uses `repeatable` / `repeatable_accounts` on create and update.
Array of account objects to publish to
The ID of the social media account
Platform-specific settings for this post. Optional except for Pinterest which requires a board\_id. The available settings depend on the platform:
Whether to restrict the post to super followers only (default: false)
Who can reply to the post. Options: 'everyone', 'following', 'mentioned\_users' (default: 'everyone')
ID of the tweet to quote (optional)
Reply settings object with 'in\_reply\_to\_tweet\_id' (optional)
ID of the community to post to (optional)
Share community post with followers too.
Custom text content for Twitter (optional) - (This allows overriding the platform-specific text content)
Poll settings with 'enabled', 'duration\_minutes', 'reply\_settings', and 'options' (optional)
everyone, following, mentionedUsers
Poll options, array of text
Type of post. Options: 'REELS', 'STORIES', 'POST' (default: 'REELS') (optional)
Custom caption for Instagram (optional) - (This allows overriding the platform-specific text content)
Type of post. Options: 'REELS', 'STORIES', 'POST' (default: 'REELS') (optional)
Custom title for the Facebook post (optional) - (This allows overriding the platform-specific text content)
URL to attach to the post (optional)
Post visibility. Options: 'PUBLIC', 'CONNECTIONS', 'LOGGED\_IN' (default: 'PUBLIC')
URL to attach to the post (optional)
Custom title for the LinkedIn post (optional) - (This allows overriding the platform-specific text content)
Type of video. Options: 'video', 'short' (default: 'video')
Video title (optional)
Video description (optional) - (This allows overriding the platform-specific text content)
Privacy status. Options: 'public', 'private', 'unlisted' (default: 'public')
Array of tags for the video (optional)
Whether the video can be embedded (default: true)
Whether the video is made for kids (default: false)
Whether to notify subscribers (default: true)
YouTube category ID
Privacy level for the video (optional) PUBLIC\_TO\_EVERYONE, MUTUAL\_FOLLOW\_FRIENDS, FOLLOWER\_OF\_CREATOR, SELF\_ONLY
Video title (optional)- (This allows overriding the platform-specific text content)
Video description (optional) - (Only available when posting photos)
Whether to disable comments (optional)
Whether to disable duets (optional)
Whether to disable stitches (optional)
Whether to mark as brand content (optional)
Whether to mark as organic brand content (optional)
Whether the content is AI-generated (optional)
Whether to auto-add music (optional)
Enum of (optional):
DIRECT\_POST: Directly post the content to TikTok account.
MEDIA\_UPLOAD: Upload content to TikTok to complete the post using TikTok's editing flow. Users will receive an inbox notification.
ID of the board to pin to
URL to attach to the pin (optional)
Pin title (optional)
Pin description (optional) - (This allows overriding the platform-specific text content)
Pin note/description (optional)
Whether to publish the pin immediately (default: true)
Custom title for the Threads post (optional) - (This allows overriding the platform-specific text content)
URL to attach to the post (optional)
Custom title for the Telegram message (optional) - (This allows overriding the platform-specific text content)
Whether to disable notifications (default: false)
Whether to protect the content (default: false)
Custom title for the Bluesky post (optional) - (This allows overriding the platform-specific text content)
Website card settings with 'uri', 'title', and 'description' (optional)
```json theme={null}
{
"workspace_id": 12,
"labels": [
5
],
"content": [
{
"text": "Check out our new reel!",
"media": [
1842
],
"cover_image": {
"thumbnail": 1843
}
},
{
"text": "Full lesson + tabs: https://jamfastguitar.com\n#guitar #practice",
"is_first_comment": true,
"first_comment_delay": 1
}
],
"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
}
}
]
}
```
### Response
Unique identifier for the created post
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.
Status of the post (draft, scheduled, published, failed)
Array of posted timestamps in workspace timezone
Scheduled date and time in workspace timezone
Whether the post is set to repeat
Number of times the post will repeat
Gap between repeats
Unit for the repeat gap (hours, days, weeks, months)
Number of remaining posts in the repeat sequence
Information about the post's workspace
Array of labels attached to the post
Array of platform-specific post information
Auto plug configuration when enabled, or `null` when off. Update via [Update post auto plug](/api-reference/posts/auto-plug).
Creation timestamp in workspace timezone
Last update timestamp in workspace timezone
```json theme={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
}
```
### Code Examples
```bash cURL theme={null}
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
}
}
]
}'
```
```javascript Node.js theme={null}
const axios = require('axios');
const createPost = async () => {
try {
const response = await axios.post('https://postsyncer.com/api/v1/posts', {
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
}
}
]
}, {
headers: {
'Authorization': 'Bearer YOUR_API_TOKEN',
'Content-Type': 'application/json'
}
});
console.log('Post created:', response.data);
} catch (error) {
console.error('Error creating post:', error.response?.data || error.message);
}
};
createPost();
```
```php PHP theme={null}
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
]
]
]
];
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://postsyncer.com/api/v1/posts');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer YOUR_API_TOKEN',
'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($httpCode === 201) {
$post = json_decode($response, true);
echo "Post created: " . $post['id'];
} else {
echo "Error: " . $response;
}
?>
```
```python Python theme={null}
import requests
import json
data = {
'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': None,
'reply': {
'in_reply_to_tweet_id': None
},
'community_id': None,
'share_with_followers': true,
'text': None
}
}
]
}
headers = {
'Authorization': 'Bearer YOUR_API_TOKEN',
'Content-Type': 'application/json'
}
response = requests.post(
'https://postsyncer.com/api/v1/posts',
json=data,
headers=headers
)
if response.status_code == 201:
post = response.json()
print(f"Post created: {post['id']}")
else:
print(f"Error: {response.status_code}")
print(response.text)
```
### 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.
```json theme={null}
"content": [
{
"text": "Clean caption for the post",
"media": [1842]
},
{
"text": "Read more: https://example.com\n#hashtags",
"is_first_comment": true,
"first_comment_delay": 1
}
]
```
**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`](/api-reference/comments/create) 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
| 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:
```json theme={null}
"content": [{
"text": "New TikTok!",
"media": [1842],
"cover_image": {"video_cover_timestamp_ms": 2500}
}]
```
**Instagram / Facebook / YouTube example** - custom cover image:
```json theme={null}
"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
Validation errors, invalid parameters, or invalid media URLs
Missing or invalid API token
Token does not have 'posts' permission
Workspace, label, or account not found
Validation errors in request data