Post

Publishing a Post

Endpoint

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

URL: /posts

Method: POST

Rate Limit: 30 requests / minute

Description

Publish a new post to a social media platform. The request must include the post content, target platform, and an accountId (fetched from GET /v2/users/me/accounts).

After submitting, poll Get Post Status with the returned postSubmissionId to track publishing progress.

Before You Start

1. Fetch your connected accounts: GET /v2/users/me/accounts (docs)

2. For Facebook/LinkedIn, fetch subaccounts to get pageId: GET /v2/users/me/accounts/{accountId}/subaccounts (docs)

3. Set content.platform and target.targetType to the same platform value (e.g., both "twitter")

---

Request Body

The request body has two top-level fields: post (required) and optional scheduling fields. Do not nest scheduling fields inside post.

Field	Type	Required	Description
post	object	Yes	The post content and metadata.
scheduledTime	string	No	ISO 8601 timestamp with timezone offset (e.g., 2026-03-04T16:30:00+00:00). If provided, useNextFreeSlot is ignored.
useNextFreeSlot	boolean	No	Schedule at the next available slot time. Defaults to false. Requires at least one calendar slot configured for the target platform.

Scheduling behavior:

• If scheduledTime is set: the post is scheduled for that time. useNextFreeSlot is ignored.

• If useNextFreeSlot is true (and no scheduledTime): the post is scheduled at the next available calendar slot for that platform.

• If neither scheduledTime nor useNextFreeSlot is provided: the post publishes immediately.

• Both fields must be root-level (siblings of post). If they are nested inside post, options, or any other object, they are ignored and the post publishes immediately.

post Object

Field	Type	Required	Description
accountId	string	Yes	The account ID from GET /v2/users/me/accounts.
content	object	Yes	The content of the post. See content below.
target	object	Yes	The target platform and platform-specific fields. See target below.

content Object

Field	Type	Required	Description
text	string	Yes	The text content of the post.
mediaUrls	array of strings	Yes	Array of media URLs. Pass any publicly accessible URL -- no upload step required. Pass [] for text-only posts.
platform	string	Yes	Must match target.targetType. Values: twitter, linkedin, facebook, instagram, pinterest, tiktok, threads, bluesky, youtube, other
additionalPosts	array	No	Additional posts for threads (Twitter, Bluesky, Threads). Each has text and mediaUrls.

target Object

The target object requires targetType and platform-specific fields. Set targetType to match content.platform.

Quick Reference: Required Fields Per Platform

Platform	targetType	Required Fields	Optional Fields
Twitter	"twitter"	(none)	(none)
LinkedIn	"linkedin"	(none)	pageId
Facebook	"facebook"	pageId	mediaType, link
Instagram	"instagram"	(none)	mediaType, altText, collaborators, coverImageUrl, shareToFeed, audioName
TikTok	"tiktok"	privacyLevel, disabledComments, disabledDuet, disabledStitch, isBrandedContent, isYourBrand, isAiGenerated	title, autoAddMusic, isDraft, imageCoverIndex, videoCoverTimestamp
Pinterest	"pinterest"	boardId	title, altText, link
Threads	"threads"	(none)	replyControl
Bluesky	"bluesky"	(none)	(none)
YouTube	"youtube"	title, privacyStatus, shouldNotifySubscribers	isMadeForKids, containsSyntheticMedia
Webhook	"webhook"	url	(none)

---

Twitter

Field	Type	Required
targetType	"twitter"	Yes

LinkedIn

Field	Type	Required	Description
targetType	"linkedin"	Yes
pageId	string	No	LinkedIn Company Page ID from subaccounts. Omit to post to personal profile.

Facebook

Field	Type	Required	Description
targetType	"facebook"	Yes
pageId	string	Yes	Facebook Page ID from subaccounts.
mediaType	"video" or "reel"	No	How to upload videos. Only applies when mediaUrls contains a video.
link	string	No	URL to attach as a link preview.

Instagram

Field	Type	Required	Description
targetType	"instagram"	Yes
mediaType	"reel" or "story"	No	Default: "reel". Has no effect on image posts.
altText	string	No	Alt text for images. Up to 1000 characters.
collaborators	array of strings	No	Instagram handles to tag (max 3). Do not include the @ sign.
coverImageUrl	string	No	Cover image URL for reels. Max 8MB.
shareToFeed	boolean	No	Share the reel to the Instagram feed. Only applies to reels.
audioName	string	No	Custom audio name for reels. You can only set this once per reel.

TikTok

Field	Type	Required	Description
targetType	"tiktok"	Yes
privacyLevel	string	Yes	SELF_ONLY, PUBLIC_TO_EVERYONE, MUTUAL_FOLLOW_FRIENDS, or FOLLOWER_OF_CREATOR
disabledComments	boolean	Yes
disabledDuet	boolean	Yes
disabledStitch	boolean	Yes
isBrandedContent	boolean	Yes
isYourBrand	boolean	Yes
isAiGenerated	boolean	Yes
title	string	No	Title for image posts. Max 90 characters. No effect on videos.
autoAddMusic	boolean	No	Add music to photo posts. No effect on videos. Default: false.
isDraft	boolean	No	Post as a draft. Drafts appear in TikTok mobile app notifications, not the Drafts folder.
imageCoverIndex	number	No	Index (starting from 0) of image to use as cover for carousels.
videoCoverTimestamp	number	No	Timestamp in milliseconds to use as video cover.

Pinterest

Field	Type	Required	Description
targetType	"pinterest"	Yes
boardId	string	Yes	Pinterest Board ID. How to get it.
title	string	No	Pin title.
altText	string	No	Pin alt text.
link	string	No	Pin URL link.

Pinterest "description" comes from the content.text field.

Threads

Field	Type	Required	Description
targetType	"threads"	Yes
replyControl	string	No	everyone, accounts_you_follow, or mentioned_only

Bluesky

Field	Type	Required
targetType	"bluesky"	Yes

YouTube

Field	Type	Required	Description
targetType	"youtube"	Yes
title	string	Yes	Video title.
privacyStatus	string	Yes	private, public, or unlisted
shouldNotifySubscribers	boolean	Yes
isMadeForKids	boolean	No	Default: false
containsSyntheticMedia	boolean	No	Whether media contains AI-generated content.

Webhook

Field	Type	Required	Description
targetType	"webhook"	Yes
url	string	Yes	The webhook URL to send the post data.

---

Response

Status Code: 201 Created

{
  "postSubmissionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Use postSubmissionId to poll Get Post Status for publishing progress.

Failed posts are visible at https://my.blotato.com/failed. The most common cause of failed posts is incorrect JSON structure.

---

Examples

1. Simplest Post (Twitter, text only)

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

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

2. Instagram Post with Images

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

{
  "post": {
    "accountId": "98434",
    "content": {
      "text": "Check out these photos!",
      "mediaUrls": [
        "https://example.com/image1.jpg",
        "https://example.com/image2.jpg"
      ],
      "platform": "instagram"
    },
    "target": {
      "targetType": "instagram"
    }
  }
}

Posting multiple images to Instagram creates a carousel.

3. Facebook Page Post

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

{
  "post": {
    "accountId": "98433",
    "content": {
      "text": "New product announcement!",
      "mediaUrls": ["https://example.com/product.jpg"],
      "platform": "facebook"
    },
    "target": {
      "targetType": "facebook",
      "pageId": "123456789"
    }
  }
}

Get accountId and pageId from the Accounts endpoints.

4. TikTok Post (all required fields)

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

{
  "post": {
    "accountId": "98435",
    "content": {
      "text": "Tips for productivity",
      "mediaUrls": ["https://example.com/video.mp4"],
      "platform": "tiktok"
    },
    "target": {
      "targetType": "tiktok",
      "privacyLevel": "PUBLIC_TO_EVERYONE",
      "disabledComments": false,
      "disabledDuet": false,
      "disabledStitch": false,
      "isBrandedContent": false,
      "isYourBrand": false,
      "isAiGenerated": true
    }
  }
}

5. Scheduled Post

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

{
  "post": {
    "accountId": "98432",
    "content": {
      "text": "This will go live later",
      "mediaUrls": [],
      "platform": "twitter"
    },
    "target": {
      "targetType": "twitter"
    }
  },
  "scheduledTime": "2025-12-25T15:00:00Z"
}

6. Twitter Thread

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

{
  "post": {
    "accountId": "98432",
    "content": {
      "text": "Here is a thread about AI content creation (1/3)",
      "mediaUrls": [],
      "platform": "twitter",
      "additionalPosts": [
        {
          "text": "First, research your topic using reliable sources (2/3)",
          "mediaUrls": []
        },
        {
          "text": "Then, create visuals and publish across platforms (3/3)",
          "mediaUrls": []
        }
      ]
    },
    "target": {
      "targetType": "twitter"
    }
  }
}

Threads work for Twitter, Bluesky, and Threads.

7. Schedule at Next Free Slot

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

{
  "post": {
    "accountId": "98432",
    "content": {
      "text": "Scheduled to the next free slot",
      "mediaUrls": [],
      "platform": "twitter"
    },
    "target": {
      "targetType": "twitter"
    }
  },
  "useNextFreeSlot": true
}

useNextFreeSlot and scheduledTime are top-level fields, not inside post.