---
title: "Create a new post"
method: POST
path: "/v2/posts"
tags: ["publishing"]
---

# Create a new post

`POST /v2/posts`

# General

Creates a new post with the provided content and optional scheduling. The post can be published immediately or scheduled for a later time.

Every post is scheduled on a queue. Failed posts are available at <https://my.blotato.com/failed>. The most common issue of failed post is incorrect JSON structure. Please make sure that JSON payload conforms to the structure described above. If you are still having trouble with identifying the issue, please contact support via Intercom and provide your `postSubmissionId`.

Post creation has a user-level rate limit of **30 requests / minute** to prevent spamming / abusing social media endpoints


# Examples

## Post to a Platform Immediately

```
POST https://backend.blotato.com/v2/posts HTTP/1.1
Content-Type: application/json
Headers:

{
  "post": {
    "accountId": "acc_12345",
    "content": {
      "text": "Hello, world!",
      "mediaUrls": [],
      "platform": "twitter"
    },
    "target": {
      "targetType": "twitter"
    }
  }
}
```

## Post at a Scheduled Time

```
POST https://backend.blotato.com/v2/posts HTTP/1.1
Content-Type: application/json

{
  "post": {
    "accountId": "acc_67890",
    "content": {
      "text": "Scheduled post example",
      "mediaUrls": [],
      "platform": "facebook"
    },
    "target": {
      "targetType": "facebook",
      "pageId": "987654321"
    }
  },
  "scheduledTime": "2025-03-10T15:30:00Z"
}
```

## Post an Image or a Video

```
POST https://backend.blotato.com/v2/posts HTTP/1.1
Content-Type: application/json

{
  "post": {
    "accountId": "acc_24680",
    "content": {
      "text": "Check out this image!",
      "mediaUrls": [
        "https://example.com/image1.jpg",
        "https://example.com/image2.jpg"
      ],
      "platform": "instagram"
    },
    "target": {
      "targetType": "instagram"
    }
  }
}
```

## Post a Twitter-like Thread with Multiple Posts

```
POST https://backend.blotato.com/v2/posts HTTP/1.1
Content-Type: application/json
Headers:

POST https://backend.blotato.com/v2/posts HTTP/1.1
Content-Type: application/json

{
  "post": {
    "accountId": "acc_13579",
    "content": {
      "text": "This is the first tweet in the thread.",
      "mediaUrls": [],
      "platform": "twitter",
      "additionalPosts": [
        {
          "text": "Here's the second tweet, adding more info.",
          "mediaUrls": []
        },
        {
          "text": "And here's the third tweet to conclude!",
          "mediaUrls": []
        }
      ]
    },
    "target": {
      "targetType": "twitter"
    }
  }
}
```

## Request body

- object
  - `post` object, required
    - `accountId` string, required — The ID of the social media account to publish the content to.
    - `content` object, required
      - `text` string, required — The text content of the post.
      - `mediaUrls` string[], required — List of media URLs to include in the post.
      - `platform` 'twitter' | 'instagram' | 'linkedin' | 'facebook' | 'tiktok' | 'pinterest' | 'threads' | 'bluesky' | 'youtube' | 'other', required — Social media platform
      - `additionalPosts` object[]
        - `text` string, required — The text content of the post.
        - `mediaUrls` string[], required — List of media URLs to include in the post.
    - `target` union, required
      - object
        - `targetType` 'webhook', required — Publish to a custom webhook.
        - `url` string, required — The URL of the webhook to publish to.
      - object
        - `targetType` 'twitter', required — Publish to Twitter.
      - object
        - `targetType` 'linkedin', required — Publish to LinkedIn.
        - `pageId` string — The ID of the LinkedIn page to publish to.
      - object
        - `targetType` 'facebook', required — Publish to Facebook.
        - `pageId` string, required — The ID of the Facebook page to publish to.
        - `mediaType` 'reel' | 'story' — Whether the media is a reel or video.
        - `link` string — Link preview to attach to the Facebook post.
        - `firstComment` string — Auto-posted comment on posts and reels, immediately after publish. Not supported for stories.
      - object
        - `targetType` 'instagram', required — Publish to Instagram.
        - `mediaType` 'reel' | 'story' — Whether the media is a reel or story.
        - `altText` string — Alternative text, for accessibility purposes. Only supported on a single image or image media in a carousel.
        - `shareToFeed` boolean — Whether to also share the reel to the Instagram feed. Only applicable for reels.
        - `audioName` string — For Reels only. Name of the audio of your Reels media. You can only rename once, either while creating a reel or after from the audio page.
        - `collaborators` string[] — List of collaborators to add to the Instagram post.
        - `coverImageUrl` string — URL of the cover image to use for the Instagram post. Use the media upload endpoint to upload media files before publishing. Maximum file size is 8MB. Only applicable to reels.
        - `trial` object — Settings for trial reels. Trial reels are shown only to non-followers.
          - `graduationStrategy` 'MANUAL' | 'SS_PERFORMANCE', required — Strategy to use to determine when to graduate post from trial (convert the trial reel to a reel, sharing it to followers).
        - `firstComment` string — Auto-posted comment with feed posts and carousels, immediately after publish. Not supported for stories. Useful for links.
      - object
        - `targetType` 'tiktok', required — Publish to TikTok.
        - `privacyLevel` 'SELF_ONLY' | 'PUBLIC_TO_EVERYONE' | 'MUTUAL_FOLLOW_FRIENDS' | 'FOLLOWER_OF_CREATOR', required — The privacy level of the TikTok post.
        - `disabledComments` boolean, required — Whether to disable comments on the TikTok post.
        - `disabledDuet` boolean, required — Whether to disable duet on the TikTok post.
        - `disabledStitch` boolean, required — Whether to disable stitch on the TikTok post.
        - `isBrandedContent` boolean, required — Whether the TikTok post is branded content.
        - `isYourBrand` boolean, required — Whether the TikTok post is for your brand.
        - `isAiGenerated` boolean, required — Whether the TikTok post is AI-generated.
        - `title` string — Title for the image posts. If notprovided, the first 90 characters of the post.content.text will be used.
        - `autoAddMusic` boolean — Whether to automatically add music to the TikTok image posts.
        - `isDraft` boolean — Don't publish the post immediately, save it as a draft instead. Default is false.
        - `imageCoverIndex` number — Index of the image (starts from 0) to use as the cover for carousel posts. Only applicable for carousel image posts.
        - `videoCoverTimestamp` number — Location in milliseconds of the video to use as the cover image. Only applicable for video posts. If not provided, the frame as 0 milliseconds will be used.
      - object
        - `targetType` 'pinterest', required — Publish to Pinterest.
        - `boardId` string, required — The ID of the Pinterest board to publish to.
        - `title` string — Title for the Pinterest post.
        - `link` string — Link for the Pinterest post.
        - `altText` string — Alternative text for the Pinterest post, for accessibility purposes.
      - object
        - `targetType` 'threads', required — Publish to Threads.
        - `replyControl` 'everyone' | 'accounts_you_follow' | 'mentioned_only' — Who can reply to the Threads post.
      - object
        - `targetType` 'bluesky', required — Publish to Bluesky.
      - object
        - `targetType` 'youtube', required — Publish to YouTube.
        - `title` string, required — Title for the YouTube post. Must not contain any of the following characters: <>
        - `privacyStatus` 'private' | 'public' | 'unlisted', required — The privacy status of the YouTube post.
        - `shouldNotifySubscribers` boolean, required — Whether to notify subscribers about the YouTube post.
        - `isMadeForKids` boolean — Whether the YouTube post is made for kids.
        - `containsSyntheticMedia` boolean — Whether the media contains synthetic content, such as AI-generated images or deepfake videos. Default is false.
        - `thumbnailUrl` string — URL of the custom thumbnail image for the YouTube video. Use the media upload endpoint to upload media files before publishing. Maximum file size is 2MB. Accepted formats: JPEG, PNG. Recommended: 1280x720 (16:9).
        - `playlistIds` string[] — YouTube playlist IDs to add the video to after upload.
  - `postDraftId` string — The ID of the existing post draft to use for creating the post. Unused in the API call
  - `useNextFreeSlot` boolean — If provided, indicates whether to use the next available free slot for scheduling the post. If set to true, the post will be scheduled at the next available slot time for the specified platform. If neither `scheduledTime` nor `slot` is provided, and this is set to true, the post will be scheduled at the next available slot time.
  - `slot` object — The schedule slot to use for scheduling the post. If neither `scheduledTime` nor `slot` is provided, the post will be published immediately.
    - `id` string, required — The ID of the schedule slot to use for scheduling.
    - `time` string, required — The timestamp (ISO 8601) when the post should be published.
  - `scheduledTime` string — The timestamp (ISO 8601) when the post should be published.

## Response `200`

Submitted

- object — Submitted
  - `postSubmissionId` string, required — The ID of the post submission. Use this ID to track the status of the post. This status code is returned when the post is already scheduled.
  - `scheduledTime` string — The resolved UTC time the post is scheduled to publish. Omitted when the post is published immediately.

## Other responses

- `201` — Submitted
- `403` — Forbidden
- `422` — Validation error
- `429` — Rate limit exceeded
- `500` — Server error

---

[API](https://skmtc.net/blotato/apis/blotato-api.md) · [All operations](https://skmtc.net/blotato/apis/blotato-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/blotato/blotato-api/revisions/c93447ba6b9d/schema)