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.

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'.

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.

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 here and enter the URL of your board.

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.

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