Publishing

Endpoints related to publishing content, such as posts and drafts.

Upload media from URL

post

General

This endpoint allows users to upload media by providing a URL. The uploaded media will be processed and stored, returning a new media URL that is used to publish a new post. Most of the platforms require validated URLs for posting images.

You can upload:

  • publicly accessible URLs

  • base64 encoded image data

Media uploads are limited to 1GB file size or smaller.

Media upload has a user-level rate limit of 10 requests / minute.

Upload Google Drive

If you have a link in google drive like this:

https://drive.google.com/file/d/18-UgDEaKG7YR7AewIDd_Qi4QCLCX5Kop/view?usp=drivesdk

You can use the following link for your Blotato "upload media" API call:

https://drive.google.com/uc?export=download&id=18-UgDEaKG7YR7AewIDd_Qi4QCLCX5Kop

Note how the IDs match: 18-UgDEaKG7YR7AewIDd_Qi4QCLCX5Kop

To see examples of how to upload to Blotato from a Google Drive, you can also check out these tutorials and templates:

n8n: https://youtu.be/D9okDd_1tBI

make: https://youtu.be/f4Stdm4lDNM

Seeing error "Google Drive can't scan this file for viruses"?

This is the most common issue when using Google Drive. When you try to access your file, you see this popup "Google Drive can't scan this file for viruses".

The issue is when you host a large video on google drive, it will show this popup, which prevents Blotato from accessing the video.

Recommended workaround: if you're regularly posting large videos (100MB+), I recommend using frame.io, an AWS S3 bucket, or similar tool where there is no issue passing around large video files.

Authorizations
Body
urlstringRequired

The URL of the media to upload.

Example: https://example.com/image.jpg
Responses
201
Default Response
application/json
post
POST /v2/media HTTP/1.1
Host: backend.blotato.com
blotato-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 39

{
  "url": "https://example.com/image.jpg"
}
{
  "url": "https://database.blotato.io/media/12345.jpg"
}

Create a new post

post

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"
    }
  }
}
Authorizations
Body
postDraftIdstringOptional

The ID of the existing post draft to use for creating the post. Unused in the API call

Example: 12345
scheduledTimestringOptional

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

Example: 2025-08-08T00:10:37.621Z
Responses
201
Submitted
application/json
post
POST /v2/posts HTTP/1.1
Host: backend.blotato.com
blotato-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 328

{
  "post": {
    "target": {
      "targetType": "tiktok",
      "isYourBrand": false,
      "autoAddMusic": false,
      "disabledDuet": false,
      "privacyLevel": "SELF_ONLY",
      "isAiGenerated": false,
      "disabledStitch": false,
      "disabledComments": false,
      "isBrandedContent": false
    },
    "content": {
      "text": "Hello, blotato!",
      "mediaUrls": [
        "https://database.blotato.io/some-media-path.mp4"
      ]
    }
  }
}
{
  "postSubmissionId": "123e4567-e89b-12d3-a456-426614174000"
}

Get post status

get

Fetches the status of a post by its submission ID. This is useful for checking if a post was successfully published or if it failed. Post lookup has a user-level rate limit of 60 requests / minute to prevent spamming / abusing social media endpoints

Authorizations
Path parameters
postSubmissionIdstringRequired

The ID of the post submission to check.

Example: 123e4567-e89b-12d3-a456-426614174000
Responses
200
Default Response
application/json
get
GET /v2/posts/{postSubmissionId} HTTP/1.1
Host: backend.blotato.com
blotato-api-key: YOUR_API_KEY
Accept: */*
{
  "postSubmissionId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "published",
  "publicUrl": "https://x.com/post/12345",
  "errorMessage": "Unsupported media type"
}

Was this helpful?