openapi: 3.1.1
info:
title: Publer Posts API
description: 'The Publer API (v1) is a RESTful JSON interface for automating social media workflows
- scheduling, publishing, media management and analytics - across Facebook, Instagram, X/Twitter,
LinkedIn, TikTok, YouTube, Pinterest, Threads, Bluesky, Mastodon, Google Business Profiles, WordPress
and Telegram. Authentication is an API key sent as `Authorization: Bearer-API YOUR_API_KEY` together
with a `Publer-Workspace-Id` header. The API is available exclusively to Publer Business users.'
termsOfService: https://publer.com/terms
contact:
name: Publer Support
email: support@publer.com
url: https://publer.com/docs
version: 1.0.0
servers:
- url: https://app.publer.com/api/v1
security:
- BearerApiAuth: []
tags:
- name: Posts
description: Endpoints for managing social media posts
paths:
/posts:
get:
summary: List Posts
description: Retrieves a list of posts based on the specified filters.
tags:
- Posts
parameters:
- schema:
type: string
name: Publer-Workspace-Id
in: header
description: ID of the workspace to retrieve posts from
required: true
- schema:
type: string
enum:
- all
- scheduled
- scheduled_approved
- scheduled_pending
- scheduled_declined
- scheduled_reauth
- scheduled_locked
- published
- published_posted
- published_deleted
- published_hidden
- draft
- draft_dated
- draft_undated
- draft_private
- draft_public
- failed
- recycling
- recycling_active
- recycling_paused
- recycling_expired
- recycling_failed
- recycling_pending
- recycling_declined
- recycling_reauth
- recycling_locked
- recurring
name: state
in: query
description: "Filter by post state\n\n Available options: \n\n `all`, `scheduled`, `scheduled_approved`,\
\ `scheduled_pending`, `scheduled_declined`, `scheduled_reauth`, `scheduled_locked`, `published`,\
\ `published_posted`, `published_deleted`, `published_hidden`, `draft`, `draft_dated`, `draft_undated`,\
\ `draft_private`, `draft_public`, `failed`, `recycling`, `recycling_active`, `recycling_paused`,\
\ `recycling_expired`, `recycling_failed`, `recycling_pending`, `recycling_declined`, `recycling_reauth`,\
\ `recycling_locked`, `recurring`"
required: false
- schema:
type: array
items:
type: string
enum:
- all
- scheduled
- scheduled_approved
- scheduled_pending
- scheduled_declined
- scheduled_reauth
- scheduled_locked
- published
- published_posted
- published_deleted
- published_hidden
- draft
- draft_dated
- draft_undated
- draft_private
- draft_public
- failed
- recycling
- recycling_active
- recycling_paused
- recycling_expired
- recycling_failed
- recycling_pending
- recycling_declined
- recycling_reauth
- recycling_locked
- recurring
style: form
explode: true
name: state
in: query
description: "Filter by multiple post states\n\n Available options: \n\n `all`, `scheduled`, `scheduled_approved`,\
\ `scheduled_pending`, `scheduled_declined`, `scheduled_reauth`, `scheduled_locked`, `published`,\
\ `published_posted`, `published_deleted`, `published_hidden`, `draft`, `draft_dated`, `draft_undated`,\
\ `draft_private`, `draft_public`, `failed`, `recycling`, `recycling_active`, `recycling_paused`,\
\ `recycling_expired`, `recycling_failed`, `recycling_pending`, `recycling_declined`, `recycling_reauth`,\
\ `recycling_locked`, `recurring`"
required: false
- schema:
type: string
format: date
name: from
in: query
description: "Filter posts scheduled/published after this date \n\n- Example: 2025-05-15 \n\n\
\ Required if `to` is provided"
required: false
- schema:
type: string
format: date
name: to
in: query
description: "Filter posts scheduled/published before this date \n\n- Example: 2025-05-15 \n\n\
\ Required if `from` is provided"
required: false
- schema:
type: integer
name: page
in: query
description: Page number for pagination
required: false
- schema:
type: array
items:
type: string
style: form
explode: true
name: account_ids
in: query
description: Filter posts by multiple account IDs
required: false
- schema:
type: string
name: query
in: query
description: Search query to filter posts by content
required: false
- schema:
type: string
enum:
- status
- link
- photo
- gif
- video
- reel
- story
- short
- poll
- document
- carousel
- article
name: postType
in: query
description: "Filter by post type \n\n Available options: \n\n `status`, `link`, `photo`, `gif`,\
\ `video`, `reel`, `story`, `short`, `poll`, `document`, `carousel`, `article`"
required: false
- schema:
type: string
name: member_id
in: query
description: Filter posts by team member ID
required: false
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/PostsListResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/401ErrorResponseWithWorkspace'
'403':
description: Permission denied or missing required scope
content:
application/json:
schema:
$ref: '#/components/schemas/403ErrorResponse'
operationId: listPosts
delete:
summary: Delete Multiple Posts
description: Deletes one or multiple posts from the workspace specifying exact post IDs. Authorization
rules apply to ensure users can only delete posts they have permission to delete.
tags:
- Posts
parameters:
- schema:
type: string
name: Publer-Workspace-Id
in: header
description: ID of the workspace containing the posts
required: true
- schema:
type: array
items:
type: string
style: form
explode: true
name: post_ids
in: query
description: Array of post IDs to delete. Can include both MongoDB ObjectIDs and PostgreSQL IDs.
required: true
responses:
'200':
description: Posts deleted successfully
content:
application/json:
schema:
type: object
properties:
deleted_ids:
type: array
description: Array of IDs of successfully deleted posts
items:
type: string
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/401ErrorResponseWithWorkspace'
'403':
description: Permission denied or missing required scope
content:
application/json:
schema:
$ref: '#/components/schemas/403ErrorResponse'
operationId: deleteMultiplePosts
/posts/schedule:
post:
summary: Schedule posts
description: Schedule one or more posts for publishing. Supports immediate publishing, scheduled
publishing, auto-scheduling, recurring posts, and more.
operationId: schedulePosts
tags:
- Posts
parameters:
- schema:
type: string
name: Publer-Workspace-Id
in: header
description: ID of the workspace to schedule posts in
required: true
responses:
'200':
description: Posts scheduled successfully
content:
application/json:
schema:
$ref: '#/components/schemas/JobResponse'
'400':
description: Invalid scheduling parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/401ErrorResponseWithWorkspace'
'403':
description: Permission denied or missing required scope
content:
application/json:
schema:
$ref: '#/components/schemas/403ErrorResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BulkPostsRequest'
description: Post scheduling parameters
required: true
/posts/schedule/publish:
post:
summary: Create post
description: Creates a new social media post. Can be scheduled for immediate publishing, future
publishing, or saved as a draft.
operationId: createPost
tags:
- Posts
parameters:
- schema:
type: string
name: Publer-Workspace-Id
in: header
description: ID of the workspace to create post in
required: true
responses:
'200':
description: Post creation job initiated
content:
application/json:
schema:
$ref: '#/components/schemas/JobResponse'
'400':
description: Invalid post data
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/401ErrorResponseWithWorkspace'
'403':
description: Permission denied or missing required scope
content:
application/json:
schema:
$ref: '#/components/schemas/403ErrorResponse'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BulkPostsRequest'
description: Post creation parameters
required: true
/posts/{id}:
put:
summary: Update Post
description: Updates an existing post. The behavior differs depending on whether the post is already
published or not.
tags:
- Posts
parameters:
- schema:
type: string
name: Publer-Workspace-Id
in: header
description: ID of the workspace containing the post
required: true
- schema:
type: string
name: id
in: path
description: ID of the post to update
required: true
responses:
'200':
description: Post updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/PostDetail'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/401ErrorResponseWithWorkspace'
'403':
description: Forbidden - You cannot update a post that has been published with approval
content:
application/json:
schema:
$ref: '#/components/schemas/403ErrorResponse'
'422':
description: Unprocessable Entity - Error message explaining why the post couldn't be updated
content:
application/json:
schema:
$ref: '#/components/schemas/422ErrorResponse'
requestBody:
content:
application/json:
schema:
type: object
properties:
post:
type: object
required:
- text
properties:
text:
type: string
description: The main content text of the post
title:
type: string
description: Title for the post (used in some networks)
description: Post update parameters
required: true
operationId: updatePost
components:
schemas:
401ErrorResponseWithWorkspace:
type: object
properties:
errors:
type: array
description: List of error messages
items:
type: string
403ErrorResponse:
type: object
properties:
errors:
type: array
description: List of error messages
items:
type: string
422ErrorResponse:
type: object
properties:
errors:
type: array
description: List of error messages
items:
type: string
BlueskyNetworkContent:
type: object
required:
- type
properties:
type:
type: string
description: Content type for Bluesky
enum:
- status
- photo
- video
- link
text:
type: string
description: Post text content
media:
type: array
description: Media items to include
items:
$ref: '#/components/schemas/MediaItem'
link:
$ref: '#/components/schemas/LinkDetails'
replyTo:
type: string
description: ID of the post to reply to
labels:
type: array
description: Self-labeled content warnings or categories
items:
type: string
BulkPostsRequest:
type: object
required:
- bulk
properties:
bulk:
type: object
required:
- state
- posts
properties:
state:
type: string
description: State of the posts
enum:
- scheduled
- draft
- draft_private
- draft_public
- recurring
posts:
type: array
description: List of posts to create
items:
type: object
required:
- networks
properties:
networks:
type: object
description: Network-specific content for the post
properties:
facebook:
$ref: '#/components/schemas/FacebookNetworkContent'
instagram:
$ref: '#/components/schemas/InstagramNetworkContent'
twitter:
$ref: '#/components/schemas/TwitterNetworkContent'
linkedin:
$ref: '#/components/schemas/LinkedInNetworkContent'
pinterest:
$ref: '#/components/schemas/PinterestNetworkContent'
google:
$ref: '#/components/schemas/GoogleBusinessNetworkContent'
youtube:
$ref: '#/components/schemas/YouTubeNetworkContent'
tiktok:
$ref: '#/components/schemas/TikTokNetworkContent'
wordpress_oauth:
$ref: '#/components/schemas/WordPressNetworkContent'
wordpress_basic:
$ref: '#/components/schemas/WordPressNetworkContent'
telegram:
$ref: '#/components/schemas/TelegramNetworkContent'
mastodon:
$ref: '#/components/schemas/MastodonNetworkContent'
threads:
$ref: '#/components/schemas/ThreadsNetworkContent'
bluesky:
$ref: '#/components/schemas/BlueskyNetworkContent'
accounts:
type: array
description: List of accounts to post to
items:
type: object
required:
- id
properties:
id:
type: string
description: Account identifier
scheduled_at:
type: string
description: Time to schedule the post
format: date-time
labels:
type: array
description: List of labels for the post
items:
type: string
previewed_media:
type: boolean
description: Whether media has been previewed
share:
type: object
description: Auto-share settings for this post
properties:
text:
type: string
description: Custom text for the shared post. If not provided, the original
post text will be used.
account_ids:
type: array
description: Array of account IDs to share the post with
items:
type: string
after:
type: object
description: When to share the post after the original is published
properties:
duration:
type: number
description: The duration value
unit:
type: string
description: The time unit (Minute, Hour, Day, Week)
enum:
- Minute
- Hour
- Day
- Week
delay:
type: object
description: Delay between sharing to multiple accounts
properties:
duration:
type: number
description: The duration value
unit:
type: string
description: The time unit (Minute, Hour, Day, Week)
enum:
- Minute
- Hour
- Day
- Week
comments:
type: array
description: Follow-up comments to be posted after the original post
items:
type: object
properties:
text:
type: string
description: The text content of the comment
language:
type: string
description: The language of the comment
delay:
type: object
description: When to post the comment after the original post is published
properties:
duration:
type: number
description: The duration value
unit:
type: string
description: The time unit (Minute, Hour, Day, Week)
enum:
- Minute
- Hour
- Day
- Week
media:
type: object
description: Media to include with the comment
properties:
type:
type: string
description: Type of media (photo, video, gif)
enum:
- photo
- video
- gif
path:
type: string
description: Path to the media file
caption:
type: string
description: Caption for the media
thumbnail:
type: string
description: Thumbnail for video media
thumbnails:
type: object
description: Different sizes of thumbnails for video media
properties:
real:
type: string
description: Full-size thumbnail
small:
type: string
description: Small thumbnail
delete:
type: object
description: Auto-delete settings for this post
properties:
hide:
type: boolean
description: If true, the post will be hidden instead of deleted (platform-dependent)
delay:
type: object
description: When to delete/hide the post after it's published
properties:
duration:
type: number
description: The duration value
unit:
type: string
description: The time unit (Minute, Hour, Day, Week)
enum:
- Minute
- Hour
- Day
- Week
recycling:
type: object
description: Recycling configuration for the post
properties:
solo:
type: boolean
description: Whether to recycle as a solo post
gap:
type: integer
description: Gap between recycles
gap_freq:
type: string
description: Frequency of the gap
enum:
- Day
- Week
- Month
start_date:
type: string
description: Start date for recycling
format: date
expire_count:
type: string
description: Number of times to recycle
expire_date:
type: string
description: Date when recycling expires
format: date
recurring:
type: object
description: Recurring configuration for the post
required:
- start_date
- end_date
- repeat
- repeat_rate
properties:
start_date:
type: string
description: Start date for recurring posts
format: date-time
end_date:
type: string
description: End date for recurring posts
format: date-time
repeat:
type: string
description: Recurrence pattern
enum:
- daily
- weekly
- monthly
- yearly
days_of_week:
type: array
description: Days of the week (0=Monday, 6=Sunday)
items:
type: integer
minimum: 0
maximum: 6
repeat_rate:
type: integer
description: Rate of repetition
share_next:
type: boolean
description: Whether to share the post next in queue
range:
type: object
description: Time range for auto-scheduled posts
properties:
start_date:
type: string
description: Start date of the range
format: date-time
end_date:
type:
- string
- 'null'
description: End date of the range
format: date-time
auto:
type: boolean
description: Whether to use auto scheduling
CarouselOptions:
type: object
description: Carousel-specific options
properties:
slides:
type: array
description: Individual slide configurations
items:
type: object
properties:
media_id:
type: string
description: Media ID for this slide
alt_text:
type: string
description: Accessibility description for this slide
caption:
type: string
description: Caption for this specific slide
ErrorResponse:
type: object
properties:
errors:
type: array
description: List of error messages
items:
type: string
FacebookNetworkContent:
type: object
required:
- type
properties:
type:
type: string
description: Content type for Facebook
enum:
- status
- photo
- video
- link
- carousel
- story
- reel
- gif
text:
type: string
description: Post text content
title:
type: string
description: Video title (for videos, truncated to 255 chars)
excerpt:
type: string
description: Post excerpt
url:
type: string
description: Link URL for link posts
post_id:
type: string
description: Facebook post ID after publishing
post_link:
type: string
description: Facebook post URL after publishing
question:
type: string
description: Poll question
duration:
type: integer
description: Poll duration in hours
details:
type: object
description: Details for the post
properties:
type:
type: string
description: Network-specific content type
enum:
- reel
- story
text_format_preset_id:
type: string
description: Background color for the post
enum:
- '106018623298955'
- '365653833956649'
- '618093735238824'
- '191761991491375'
- '2193627793985415'
- '200521337465306'
- '1821844087883360'
- '177465482945164'
- '160419724814650'
- '248623902401250'
- '240401816771706'
- '1868855943417360'
- '255989551804163'
- '1792915444087912'
- '1654916007940525'
- '1679248482160767'
- '518948401838663'
- '423339708139719'
- '204187940028597'
- '621731364695726'
- '518596398537417'
- '134273813910336'
- '217321755510854'
- '323371698179784'
- '901751159967576'
- '552118025129095'
- '263789377694911'
- '606643333067842'
- '458988134561491'
- '548109108916650'
- '175493843120364'
- '338976169966519'
- '206513879997925'
- '168373304017982'
- '1271157196337260'
- '174496469882866'
- '862667370603267'
- '127541261450947'
- '218067308976029'
- '688479024672716'
- '238863426886624'
- '301029513638534'
- '154977255088164'
- '1941912679424590'
- '396343990807392'
- '143093446467972'
- '161409924510923'
- '145893972683590'
- '217761075370932'
- '931584293685988'
- '148862695775447'
- '100114277230063'
- '558836317844129'
- '172497526576609'
- '433967226963128'
- '197865920864520'
- '643122496026756'
- '762009070855346'
- '228164237768720'
- '146487026137131'
- '221828835275596'
- '1903718606535395'
- '1881421442117417'
- '249307305544279'
- '1777259169190672'
- '303063890126415'
- '122708641613922'
- '319468561816672'
- '121945541697934'
- '288211338285858'
- '446330032368780'
- '219266485227663'
- '1289741387813798'
- '1365883126823705'
feed:
type: boolean
description: Whether to share the reel to feed
reminder:
type: boolean
description: Use reminder publishing instead of API
audio:
# --- truncated at 32 KB (60 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/publer/refs/heads/main/openapi/publer-posts-api-openapi.yml