Publish Post /v2/posts

Publishing a Post

Endpoint

Base URL: https://backend.blotato.com/v2

URL: /posts

Method: POST

Description

This endpoint allows users to publish a new post on supported platforms. The request must include the post content, the target platform, and optionally a scheduled time.

Request

Request Body

The request body must contain the following fields:

Field
Type
Required
Description

post

object

βœ…

The post content and metadata.

scheduledTime

string

❌

The timestamp (ISO 8601) when the post should be published.

post Object

Field
Type
Required
Description

accountId

string

βœ…

The ID of the connected account for publishing the post.

content

object

βœ…

The content of the post. See content structure below.

target

object

βœ…

The target platform where the post will be published. See target structure below.

content Object

Field
Type
Required
Description

text

string

βœ…

The main textual content of the post.

mediaUrls

Array<string>

βœ…

An array of media URLs attached to the post. The URLs must originate from the blotato.com domain. See the Upload Media section for more info.

platform

'twitter' | 'linkedin' | 'facebook' | 'instagram' | 'pinterest' | 'tiktok' | 'threads' | 'bluesky' | 'youtube' | 'other'

βœ…

The platform type where the post will be published. Must match exactly.

additionalPosts

Array<AdditionalPost>

❌

An array of additional posts, if applicable. See additionalPosts structure below. This works for all platforms that support threads-like posts (e.g. Twitter, Bluesky, Threads)

additionalPosts Array

Each element in the additionalPosts array follows the same structure as the content object.

Field
Type
Required
Description

text

string

βœ…

The main textual content of the additional post.

mediaUrls

Array<string>

βœ…

An array of media URLs attached to the additional post.

target Object

The target object specifies the platform for publishing. It must match one of the supported platform structures below:

Webhook

Field
Type
Required
Description

targetType

'webhook'

βœ…

url

string

βœ…

The webhook URL to send the post data.

Twitter

Field
Type
Required
Description

targetType

'twitter'

βœ…

LinkedIn

Field
Type
Required
Description

targetType

'linkedin'

βœ…

pageId

string

❌

Optional LinkedIn Page ID.

Facebook

Field
Type
Required
Description

targetType

'facebook'

βœ…

pageId

string

βœ…

Facebook Page ID.

mediaType

'video' | 'reel'

❌

Determines whether the video will be uploaded as a regular video or a reel. Only applicable if one of the mediaUrls is a video.

Instagram

Field
Type
Required
Description

targetType

'instagram'

βœ…

mediaType

'reel' | 'story'

❌

Is it a story or a reel? Reels are video only cannot appear in carousel items. Setting reels on an image post has no effect. The default value is 'reel'.

altText

string

❌

Alternative text, up to 1000 character, for an image. Only supported on a single image or image media in a carousel.

TikTok

Field
Type
Required
Description

targetType

'tiktok'

βœ…

privacyLevel

'SELF_ONLY' | 'PUBLIC_TO_EVERYONE' | 'MUTUAL_FOLLOW_FRIENDS' | 'FOLLOWER_OF_CREATOR'

βœ…

Privacy level of the post. Must match exactly

disabledComments

boolean

βœ…

Whether comments are disabled.

disabledDuet

boolean

βœ…

Whether duet is disabled.

disabledStitch

boolean

βœ…

Whether stitch is disabled.

isBrandedContent

boolean

βœ…

Whether the post is branded content.

isYourBrand

boolean

βœ…

Whether the content belongs to the user's brand.

isAiGenerated

boolean

βœ…

Whether the content is AI-generated.

title

string

❌

Title for the image posts. Must be less than 90 characters. Has no effect on video posts. Defaults to the first 90 characters of the post.content.text.

autoAddMusic

boolean

❌

Automatically add recommended music to photo posts. Has no effect on video posts. Default: false

Pinterest

Field
Type
Required
Description

targetType

'pinterest'

βœ…

boardId

string

βœ…

Pinterest board ID.

title

string

❌

Pin title

altText

string

❌

Pin alternative text

link

string

❌

Pin URL Link

To get your Pinterested boardId, go to the Remix screen, create a draft Pinterest post, and click "Publish". You'll see your board IDs.

Pinterest "description" comes from the "text" field you pass in.

Threads

Field
Type
Required
Description

targetType

'threads'

βœ…

replyControl

'everyone' | 'accounts_you_follow' | 'mentioned_only'

❌

Who can reply (optional).

Bluesky

Field
Type
Required
Description

targetType

'bluesky'

βœ…

YouTube

Field
Type
Required
Description

targetType

'youtube'

βœ…

title

string

βœ…

Video title.

privacyStatus

'private' | 'public' | 'unlisted'

βœ…

Video privacy status.

shouldNotifySubscribers

boolean

βœ…

Whether to notify subscribers.

isMadeForKids

boolean

❌

YouTube's "Is Made For Kids?" option. Default: false.

Responses

Success Response

Status Code: 201 Created

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.

Response Body:

{
  "postSubmissionId": "<UNIQUE_POST_SUBMISSION_ID>"
}

Error Responses

Too Many Requests

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

Status Code: 429 Too many requests

{
  "statusCode": 429,
  "message": "Rate limit exceeded, retry in 49 seconds"
}

Examples

1. 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"
    }
  }
}

2. 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"
}

3. Attach Media to a Post

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"
    }
  }
}

4. Post a Twitter Thread with Multiple Posts

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"
    }
  }
}

Last updated

Was this helpful?