Blotato Help
Blotato Help
  • 🍄Welcome to Blotato!
  • Getting Started
    • 🔥Make Your First 5 Posts
    • 📚Understanding Sources
    • 📅Content Calendar Setup
  • Support
    • 🆘Office Hours
    • ⛑️Get Support
    • 🧠FAQs
  • FEATURES
    • 🎥AI Videos
      • Make Your First AI Video
      • Recommended Workflow
      • Multiple Languages
      • AI Video Credits
      • AI Voiceover Captions
      • Custom Assets
      • Viral Format Examples
      • Troubleshooting
      • FAQs
    • 🖼️AI Images
      • AI Image Credits
    • 💠Inspiration
      • Tutorial
      • Search Topics
      • Shuffle
      • Apply Filters
      • Find Influencers
      • Remix Posts
      • Request Topics
    • 📅Content Calendar
      • Tutorial
      • Create Schedule
      • Schedule Posts
      • Timezone
  • PLATFORMS
    • Linkedin
      • Connect Accounts
      • Supported Posts & Media
      • Best Practices Playbook
      • Repurpose Linkedin Posts
      • Suggested Prompts
      • Troubleshooting
    • Tiktok
      • Connect Accounts
      • Supported Posts & Media
      • Brand New Accounts
      • Best Practices Playbook
      • Brainstorm Tiktok Hooks
      • Repurpose Tiktok Posts
      • Suggested Prompts
      • Troubleshooting
    • Youtube
      • Connect Accounts
      • Troubleshooting
      • FAQs
  • Tips and Tricks
    • 🪝Hooks
    • Growth best practices
    • Search viral trending news
    • Use viral post as template
    • Make output sound like you
    • Manage multiple brand voices
    • Make small edits
    • Translate languages
    • Working on multiple drafts
    • Twitter threads
    • Youtube scripts
    • Social Platform Requirements
  • API
    • Quickstart
    • Make.com
      • Make Basics
      • Make AI Clone
      • Make Faceless Videos
      • Make AI Social Media System
      • Make Slideshows & Carousels
      • Troubleshooting
    • n8n
      • n8n Basics
      • n8n AI Clone
      • n8n Faceless Videos
      • n8n Slideshows & Carousels
      • Troubleshooting
  • API Reference
    • Publish Post /v2/posts
    • Upload Media /v2/media
    • Create Video /v2/videos/creations
    • Find Video /v2/videos/creations/:id
    • Voice IDs
  • Troubleshooting API Errors
  • FAQs
  • Settings
    • Social accounts
      • Facebook
      • Instagram
      • Linkedin
    • API keys
    • Billing & Credits
    • Team access
    • Affiliates
    • FAQs
  • Open Blotato
Powered by GitBook
On this page
  • Publishing a Post
  • Endpoint
  • Description
  • Request
  • Responses
  • Examples
  1. API Reference

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

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.

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

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

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"
    }
  }
}
PreviousAPI ReferenceNextUpload Media /v2/media

Last updated 10 days ago

To get your Pinterested boardId, go and enter the URL of your board.

Every post is scheduled on a queue. Failed posts are available at . 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.

here
https://my.blotato.com/failed