Uploads media to Blotato by passing a publicly accessible URL or base64-encoded image data and returns a hosted media URL to use when publishing posts. Supports files up to 200MB, with a presigned-upload flow for local files.
openapi: 3.0.1
info:
title: Blotato API
description: >-
The Blotato API lets you upload media, publish and schedule posts to social
platforms (Twitter/X, Instagram, LinkedIn, Facebook, TikTok, Pinterest,
Threads, Bluesky, YouTube), generate AI videos and visuals from templates,
and retrieve connected accounts. All requests are authenticated with a
blotato-api-key header.
termsOfService: https://www.blotato.com/terms
contact:
name: Blotato Support
url: https://help.blotato.com
version: '2.0'
servers:
- url: https://backend.blotato.com/v2
description: Blotato REST API v2
security:
- blotatoApiKey: []
tags:
- name: Media
description: Upload media for use in posts.
- name: Posts
description: Publish, schedule, and track posts.
- name: Visuals
description: AI video and visual generation from templates.
- name: Accounts
description: User and connected social account lookup.
paths:
/media:
post:
operationId: uploadMedia
tags:
- Media
summary: Upload media from a URL
description: >-
Uploads media to Blotato by passing a publicly accessible URL or a
base64-encoded image data URL. Returns a Blotato-hosted media URL to use
in the mediaUrls of a post. Files up to 200MB are supported.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UploadMediaRequest'
responses:
'200':
description: Media uploaded.
content:
application/json:
schema:
$ref: '#/components/schemas/UploadMediaResponse'
'401':
description: Missing or invalid API key.
'429':
description: Rate limit exceeded.
/posts:
post:
operationId: publishPost
tags:
- Posts
summary: Publish a post
description: >-
Publishes or schedules a post to a connected social account. Returns a
postSubmissionId; poll GET /posts/{postSubmissionId} to track status.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PublishPostRequest'
responses:
'201':
description: Post submission accepted.
content:
application/json:
schema:
$ref: '#/components/schemas/PublishPostResponse'
'401':
description: Missing or invalid API key.
'422':
description: Validation error.
'429':
description: Rate limit exceeded.
'500':
description: Server error.
/posts/{postSubmissionId}:
get:
operationId: getPostStatus
tags:
- Posts
summary: Get post status
description: Returns the publishing status for a post submission.
parameters:
- name: postSubmissionId
in: path
required: true
schema:
type: string
responses:
'200':
description: Post submission status.
content:
application/json:
schema:
$ref: '#/components/schemas/PostStatusResponse'
'401':
description: Missing or invalid API key.
'404':
description: Post submission not found.
/users/me:
get:
operationId: getCurrentUser
tags:
- Accounts
summary: Get current user
description: Retrieves information about the authenticated user.
responses:
'200':
description: Current user.
'401':
description: Missing or invalid API key.
/users/me/accounts:
get:
operationId: listAccounts
tags:
- Accounts
summary: List connected accounts
description: >-
Returns the authenticated user's connected social accounts, optionally
filtered by platform. Provides the accountId values used when publishing.
parameters:
- name: platform
in: query
required: false
schema:
type: string
responses:
'200':
description: Connected accounts.
'401':
description: Missing or invalid API key.
/users/me/accounts/{accountId}/subaccounts:
get:
operationId: listSubaccounts
tags:
- Accounts
summary: List subaccounts
description: >-
Returns subaccounts for an account (for example LinkedIn or Facebook
pages) associated with the given accountId.
parameters:
- name: accountId
in: path
required: true
schema:
type: string
responses:
'200':
description: Subaccounts.
'401':
description: Missing or invalid API key.
/social/pinterest/boards:
get:
operationId: listPinterestBoards
tags:
- Accounts
summary: List Pinterest boards
description: Lists the Pinterest boards available for a connected account.
responses:
'200':
description: Pinterest boards.
'401':
description: Missing or invalid API key.
/videos/templates:
get:
operationId: listVisualTemplates
tags:
- Visuals
summary: List visual templates
description: >-
Lists the available AI video and visual templates, returning the
templateId values and the inputs each template accepts.
responses:
'200':
description: Available templates.
'401':
description: Missing or invalid API key.
/videos/from-templates:
post:
operationId: createVisual
tags:
- Visuals
summary: Create a visual from a template
description: >-
Creates an AI video or visual creation from a template plus inputs.
Returns a creation id and an initial status; poll
GET /videos/creations/{id} until the creation is done.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateVisualRequest'
responses:
'201':
description: Visual creation queued.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateVisualResponse'
'401':
description: Missing or invalid API key.
'422':
description: Validation error.
/videos/creations/{id}:
get:
operationId: getVisualStatus
tags:
- Visuals
summary: Get visual creation status
description: >-
Returns the status of a visual creation. When done, the response
includes a mediaUrl for videos or imageUrls for images and carousels.
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Visual creation status.
'401':
description: Missing or invalid API key.
'404':
description: Creation not found.
components:
securitySchemes:
blotatoApiKey:
type: apiKey
in: header
name: blotato-api-key
description: >-
API key generated in Blotato Settings > API. Sent in the blotato-api-key
header on every request. Keys may include trailing '=' padding that must
be preserved.
schemas:
UploadMediaRequest:
type: object
required:
- url
properties:
url:
type: string
description: >-
A publicly accessible media URL, or a base64-encoded image data URL,
to upload to Blotato.
UploadMediaResponse:
type: object
properties:
url:
type: string
description: The Blotato-hosted media URL to reference in a post.
PublishPostRequest:
type: object
required:
- post
properties:
post:
$ref: '#/components/schemas/Post'
scheduledTime:
type: string
format: date-time
description: ISO 8601 time at which to publish the post (optional).
useNextFreeSlot:
type: boolean
description: Publish at the next free scheduling slot (optional).
slot:
$ref: '#/components/schemas/Slot'
Post:
type: object
required:
- accountId
- content
- target
properties:
accountId:
type: string
description: The connected account id, from GET /users/me/accounts.
content:
$ref: '#/components/schemas/PostContent'
target:
$ref: '#/components/schemas/PostTarget'
PostContent:
type: object
required:
- text
- mediaUrls
- platform
properties:
text:
type: string
description: The post text/caption.
mediaUrls:
type: array
maxItems: 20
items:
type: string
description: Hosted media URLs (for example from POST /media).
platform:
type: string
description: The destination platform for this content.
enum:
- twitter
- instagram
- linkedin
- facebook
- tiktok
- pinterest
- threads
- bluesky
- youtube
- other
additionalPosts:
type: array
maxItems: 10
description: Additional posts for threads/carousels.
items:
type: object
required:
- text
- mediaUrls
properties:
text:
type: string
mediaUrls:
type: array
maxItems: 20
items:
type: string
PostTarget:
type: object
required:
- targetType
description: >-
Platform-specific target. The targetType selects the platform; some
platforms require additional fields (for example linkedin/facebook
pageId, pinterest boardId, youtube title/privacyStatus, tiktok privacy
and content-disclosure flags).
properties:
targetType:
type: string
enum:
- twitter
- instagram
- linkedin
- facebook
- tiktok
- pinterest
- threads
- bluesky
- youtube
- webhook
pageId:
type: string
description: Required for linkedin and facebook page targets.
boardId:
type: string
description: Required for pinterest targets.
mediaType:
type: string
description: Optional content variant, for example reel or story.
title:
type: string
description: Title (youtube, pinterest).
privacyStatus:
type: string
description: Required for youtube targets.
privacyLevel:
type: string
description: Required for tiktok targets.
url:
type: string
description: Required for webhook targets.
Slot:
type: object
required:
- id
- time
properties:
id:
type: string
time:
type: string
PublishPostResponse:
type: object
properties:
postSubmissionId:
type: string
description: Identifier used to poll publishing status.
PostStatusResponse:
type: object
properties:
postSubmissionId:
type: string
status:
type: string
description: Current publishing status of the submission.
CreateVisualRequest:
type: object
required:
- templateId
- inputs
properties:
templateId:
type: string
description: A template id from GET /videos/templates.
inputs:
type: object
description: Template-specific inputs.
prompt:
type: string
render:
type: boolean
isDraft:
type: boolean
title:
type: string
useBrandKit:
type: boolean
CreateVisualResponse:
type: object
properties:
item:
type: object
properties:
id:
type: string
status:
type: string
description: Initial creation status, for example queueing.