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

apiKey

blotato-api-keystringRequired

Body

application/json

urlstringRequired

The URL of the media to upload.

Example: https://example.com/image.jpg

Responses

201

Default Response

application/json

422

Validation error

application/json

429

Rate limit exceeded

application/json

500

Server error

application/json

post

/v2/media

HTTPcURLJavaScriptPython

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",
  "id": "media_12345"
}

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

apiKey

blotato-api-keystringRequired

Body

application/json

postDraftIdstringOptional

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

Example: 12345

useNextFreeSlotbooleanOptional

If provided, indicates whether to use the next available free slot for scheduling the post. If set to true, the post will be scheduled at the next available slot time for the specified platform. If neither scheduledTime nor slot is provided, and this is set to true, the post will be scheduled at the next available slot time.

scheduledTimestringOptional

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

Example: 2026-03-17T18:43:00.631Z

Responses

201

Submitted

application/json

422

Validation error

application/json

429

Rate limit exceeded

application/json

500

Server error

application/json

post

/v2/posts

HTTPcURLJavaScriptPython

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

apiKey

blotato-api-keystringRequired

Path parameters

postSubmissionIdstringRequired

The ID of the post submission to check.

Example: 123e4567-e89b-12d3-a456-426614174000

Responses

200

Default Response

application/json

postSubmissionIdstringRequired

The ID of the post submission.

Example: 123e4567-e89b-12d3-a456-426614174000

statusstring · enumRequired

The current status of the post.

Example: publishedPossible values:

scheduledTimestringOptional

The scheduled time of the post if it is scheduled. Null if the post was published immediately.

Example: 2025-03-11T15:30:00.000Z

publicUrlstringOptional

The public URL of the post if it was published.

Example: https://x.com/post/12345

errorMessagestringOptional

The error message if the post failed.

Example: Unsupported media type

404

Not found

application/json

429

Rate limit exceeded

application/json

500

Server error

application/json

get

/v2/posts/{postSubmissionId}

HTTPcURLJavaScriptPython

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",
  "scheduledTime": "2025-03-11T15:30:00.000Z",
  "publicUrl": "https://x.com/post/12345",
  "errorMessage": "Unsupported media type"
}

Resolves a source asynchronously

post

Submits a source for asynchronous resolution. The response contains a source resolution ID that can be used to check the status of the resolution. A source can be any text content, URL, or other data that needs to be processed to generate a title and content. Source resolution has a user-level rate limit of 30 requests / minute.

Authorizations

apiKey

blotato-api-keystringRequired

Body

application/json

sourceone ofRequired

or

or

or

or

or

or

or

customInstructionsstringOptional

Responses

201

Default Response

application/json

422

Validation error

application/json

500

Default Response

application/json

post

/v2/source-resolutions-v3

HTTPcURLJavaScriptPython

POST /v2/source-resolutions-v3 HTTP/1.1
Host: backend.blotato.com
blotato-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 74

{
  "source": {
    "sourceType": "text",
    "text": "text"
  },
  "customInstructions": "text"
}

{
  "id": "text"
}

Get source resolution status

get

Fetches the status of a source resolution by its ID. This endpoint allows users to check whether the source has been resolved or is still in the queue. Source resolution lookup has a user-level rate limit of 60 requests / minute.

Authorizations

apiKey

blotato-api-keystringRequired

Path parameters

idstringRequired

Responses

200

Default Response

application/json

or

or

or

404

Not found

application/json

500

Default Response

application/json

get

/v2/source-resolutions-v3/{id}

HTTPcURLJavaScriptPython

GET /v2/source-resolutions-v3/{id} HTTP/1.1
Host: backend.blotato.com
blotato-api-key: YOUR_API_KEY
Accept: */*

{
  "id": "text",
  "status": "completed",
  "title": "text",
  "content": "text",
  "referenceUrl": "text"
}