Retrieve profile and application settings for the currently authenticated user. Use this endpoint to adapt your integration to user preferences and entitlements.
Manage organizational units (“workspaces”) that group social accounts, members, and content. Workspaces help agencies, brands, and departments keep clients and campaigns separate under a single Publer login.
Requirements
Authentication: Bearer API token
Scope: workspaces
Headers:
Authorization: Bearer-API YOUR_API_KEY
Endpoint
List Workspaces
Retrieve all workspaces accessible by the authenticated user.
Working with Workspaces
A user can belong to multiple workspaces.
Each workspace has its own accounts, posts, and settings.
Use the workspace context (Publer-Workspace-Id header) to target API calls at the correct workspace.
Workspace Context for Other Endpoints
Many endpoints require you to specify which workspace you’re operating in. Include the Publer-Workspace-Id header:
Related Resources
- Access user profile information
- Access social accounts within workspaces
— Create, schedule, and manage content
Draft Posts
Create, manage, and collaborate on draft posts that aren't published immediately. Drafts help you save work-in-progress content, collaborate with your team, and schedule posts for later publishing.
Overview
Draft posts are unfinished posts connected to a social account. They can be:
Introduction
BUSINESS ACCESS ONLY: The Publer API is currently available exclusively to Publer Business users.
What Is the Publer API?
A RESTful JSON interface for automating social media workflows—scheduling, publishing, media management, and analytics—across multiple networks.
Authentication
Every Publer API request must include a valid API key. This guide shows you how to obtain, use, and manage your keys securely.
Obtaining an API Key
Sign in to your Publer account (Business plan).
Platform-Specific Formats
Each social network offers unique post formats. Publer’s API supports these specialized types—click a format to dive into its implementation details:
Dated drafts: drafts with a set date/time (these typically show up in Calendar views in the UI).
Undated drafts: drafts without a set date/time (stored under Drafts in the UI for later review/scheduling).
Draft Posts are created via the scheduling endpoint using:
bulk.state = "draft"
Draft Posts support the same post structures as normal scheduled/published posts, meaning you can create different kinds of drafts (photos, videos, carousels, reels, etc.) depending on the provider.
Endpoint
Use the scheduling endpoint with bulk.state: "draft" to save work-in-progress content without publishing.
Request Headers
Header
Required
Value
Authorization
Yes
Bearer-API YOUR_API_KEY
Publer-Workspace-Id
Yes
Workspace ID
Content-Type
Yes
application/json
Accept
No
application/json (default)
Draft Type & Example
Account-Connected Draft (draft)
Drafts connected to specific social accounts that can optionally include scheduling information.
Key Features
Must include accounts array with account IDs
Can include scheduled_at for future publishing (dated drafts)
Uses specific network keys (e.g., facebook, instagram, twitter, etc.)
Example Request
Parameters
Bulk
Field
Type
Required
Description
bulk.state
string
Yes
Must be "draft" for Draft Posts
bulk.posts
array
Yes
List of posts to create
Post Object
Field
Type
Required
Description
posts[].networks
object
Yes
Network configurations for the post (use provider keys like facebook, instagram, etc.)
posts[].accounts
array
Yes
Social accounts the draft is connected to
Accounts (required for Draft Posts)
Field
Type
Required
Description
accounts[].id
string
Yes
Social account ID
accounts[].scheduled_at
string
No
ISO 8601 timestamp. If provided, the draft becomes a dated draft. If omitted, it’s an undated draft.
Network Configuration
For Draft Posts (bulk.state = "draft"), use specific provider keys inside posts[].networks (e.g. facebook, instagram, twitter, etc.).
The network payload structure depends on the provider and content type (e.g., status, photo, video, carousel, story, reel, etc.).
Draft Posts support the same payload shapes as scheduled/published posts.
Content Types
Draft Posts can be created using any supported content type (the type field inside networks.[provider]).
Include your API key and workspace ID on almost every request:
Request Format
GET
Use query parameters for filters and pagination:
POST, PUT, PATCH
Send JSON in the request body:
DELETE
No request body is required (unless otherwise noted):
Response Format
All responses are JSON.
Success
Synchronous endpoints return the requested resource or collection.
Asynchronous endpoints (e.g., post creation) return a job_id:
Error
Status codes indicate general error type (4xx, 5xx).
The response body contains an errors array:
Common HTTP Status Codes
200 OK
201 Created
202 Accepted (async)
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
429 Too Many Requests
500 Internal Server Error
Versioning
Current version: v1 (in the URL path).
We follow Semantic Versioning. Breaking changes only occur on MAJOR version bumps; you will be notified in advance.
Asynchronous Operations
Submit your request → 202 Accepted + {"job_id": "…"}
Use full ISO 8601 format, including timezone (e.g., 2025-06-01T09:00:00+02:00).
Timestamps must be at least 1 minute in the future.
Best Practices
Buffer Time: Space posts 1–2 minutes apart to avoid collisions.
Timezone Awareness: Schedule using your audience’s local time.
Batch Scheduling: Combine related posts in a single request for efficiency.
Related Topics
- Details on different content formats
- Advanced AI-based scheduling options
- Setting up repeating content
Deleting Posts
Remove one or multiple posts—of any state—from your workspace. This endpoint enforces role-based permissions and state-specific restrictions.
Requirements
Authentication: Bearer API token
Scope: posts
Headers:
Authorization: Bearer-API YOUR_API_KEY
Publer-Workspace-Id: YOUR_WORKSPACE_ID
Endpoint
Deletes one or more posts based on the provided IDs.
Query Parameters
Authorization Rules
You may delete:
Posts you created
Posts in workspaces you own
Pending-state deletions trigger a notification to the creator before removal.
Related Resources
- Retrieve and filter posts
- Modify existing posts
Accounts
Manage and retrieve social media accounts connected to your Publer workspaces. Use these accounts as targets when scheduling or publishing content.
Requirements
Authentication: Bearer API token
Best Times to Post
The Best Times to Post endpoint returns a heatmap of optimal posting times for a specific account, based on historical performance. Use it to power schedule suggestions, calendar overlays, and autofill routines.
Requirements
Authentication: Bearer API token
Scope:analyticsHeaders:
Post with Signature
Automatically append a branded or informative signature to your social posts. Signatures help drive consistency and professionalism across your accounts.
Overview
A signature is a reusable block of text (such as a disclaimer, call-to-action, or branded tagline) you can attach to posts on supported networks. You can manage multiple signatures per account and select which one to append when scheduling or publishing.
Overview
Access & Availability
The Publer API is available exclusively to Business and Enterprise customers.
Introduction
Welcome to the Publer API. This RESTful JSON API brings Publer’s social media scheduling, publishing, and analytics capabilities into your own applications, scripts, or services. Whether you’re automating campaigns, building dashboards, or integrating content workflows, the Publer API provides the same power you know from the Publer web platform.
Twitter/X Long-Form Posts
Unlock the ability to schedule and publish long-form posts (up to 25,000 characters) to Twitter/X using the Publer API—exclusively for accounts with an X Premium subscription.
Overview
Twitter/X supports long-form posts (sometimes called "long posts" or "extended tweets") for users with an X Premium (formerly Twitter Blue) subscription, even at the Basic tier. These posts can contain up to 25,000 characters, far exceeding the standard 280-character limit.
With Publer, you can programmatically schedule and publish long-form posts via the API. Publer automatically detects your account’s eligibility and switches to the appropriate post type.
Accounts with X Premium:
You can create and schedule long-form posts up to 25,000 characters.
Accounts without X Premium:
Your post text will be truncated to the standard 280-character limit, and the long-form post type will be disabled.
Tip: Validate the post length in your integration to avoid surprises when publishing.
Key Differences
Long-form posts are not the same as Twitter threads. Threads are multiple connected posts; long-form posts are a single post with expanded character count.
Scheduling long-form posts is not possible directly on X/Twitter—use Publer’s API or platform to achieve this functionality.
Request Example
To schedule a Twitter/X long-form post, set the network type to "long_post" inside the details object for the "twitter" network:
Field
Type
Description
networks.twitter.details.type
string
Must be "long_post" for long-form posts
networks.twitter.text
string
Content of your long-form post (max 25,000 characters with X Premium)
Important Notes
X Premium Required: Only X Premium accounts can publish long-form posts. For other accounts, posts will be truncated to 280 characters.
Not for Threads: Use this format for single extended posts, not for multi-part threads.
API Detection: Publer automatically detects account eligibility for long-form posting.
Scheduling Limitation: Twitter/X doesn’t natively support scheduling long-form posts; this is enabled via Publer’s platform and API.
Best Practices
Check your account’s X Premium status before relying on long-form functionality.
Always validate post length to ensure your content is not unintentionally truncated.
Use long-form posts for in-depth announcements, articles, or detailed updates—threads remain better for sequential storytelling.
Retrieve all social media accounts in a workspace.
Retrieves a list of all social media accounts available in the specified workspace.
The list of accounts returned will include all social media accounts that you have connected to your Publer workspaces and have permission to access. These accounts can be used to schedule and publish content via the Posts API.
The accounts data provides important information about the social media profiles available for posting, including their configuration settings and current synchronization status.
Supported Providers
Publer supports these network providers and account types:
Retrieves a day/hour heatmap of posting performance tailored to the audience of the specified account. Optionally include competitor data and restrict to a custom date range.
URL Parameter
Parameter
Type
Required
Description
account_id
string
No
Social account to analyze. Omit for all workspace accounts.
Query Parameters
Parameter
Type
Required
Description
competitors
string
No
For competitor data. true or false (default false).
competitor_id
string
No
Analyze a specific competitor (requires competitors=true).
from
date (YYYY-MM-DD)
Yes
Structure
Object keyed by day of week (Monday..Sunday).
Each day maps to an array of 24 numbers (hour indexes 0..23).
Each number is a relative engagement/performance score (higher = better posting time). Use for ranking and heatmap intensity; not a percentage.
Notes
Default window: If no dates are provided, best times are computed from recent history (commonly last 7 days).
Workspace/account settings (e.g., “day starts at” and “week starts on”) influence the visualization in the app; the API always returns 24 hourly slots per day.
Heatmap scores are relative within the dataset; normalize in your UI if combining multiple accounts.
Competitor view requires competitors=true; use competitor_id to focus on a single competitor.
Data refreshes automatically (about every 24 hours). Use Sync Insights in the UI for on‑demand refresh.
The Media API lets you list and filter items in your library. You can page through results, query by IDs, or apply filters such as type, usage status, source, and search terms.
Requirements
Authentication: Bearer API token
Scope: media
Headers:
Authorization: Bearer-API YOUR_API_KEY
Publer-Workspace-Id: YOUR_WORKSPACE_ID
Endpoint
List Media
Retrieve all social media accounts in a workspace.
Query Parameters
Parameter
Type
Required
Description
Notes
Free trial users see placeholder data unless they supply specific query filters.
Paid accounts have full library access.
Related Resources
— Manage connected social accounts
— Create and schedule posts
— Upload new media files
Quickstart Guide
BUSINESS ACCESS ONLY: The Publer API is currently available exclusively to Publer Business users.
This guide walks you through the core steps to integrate with Publer’s API in minutes. By the end, you’ll have published your first scheduled post.
Prerequisites
A Business Publer account
Basic familiarity with HTTP/JSON APIs
A command-line tool (curl) or API client (Postman, Insomnia)
Step 1: Generate an API Key
Sign in to Publer and verify you have Business plan access.
Go to Settings → Access & Login →API Keys.
Click Create API Key.
Step 2: List Workspaces
Before making other requests, let's retrieve your workspaces. The workspace ID is required in the header for most API operations:
Sample Response
Now you can use a workspace ID in your subsequent requests by including it in the header:
Step 3: List Social Accounts
Next, let's retrieve the social media accounts in your workspace. You'll need the account IDs to specify where to publish your posts:
Expected Response
Make note of the account IDs as you'll need them to specify where to publish your content in the next step.
Step 4: Create a Scheduled Post
Make your first scheduled post with one API call:
Sample Response
The API returns a job ID that you can use to check the status of your request:
Step 5: Poll Job Status
Posts are created asynchronously. Use the returned job_id to check progress:
Successful Job Response
Failed Job Response
If there's an error with your request, the response will include details about what went wrong:
Step 6: Verify Scheduled Posts
List your scheduled posts to confirm creation:
Sample Response
Understanding the Workflow
Generate an API key
List workspaces → pick a workspace ID
List accounts → pick account IDs
This async pattern scales across multiple workspaces, accounts, and post types.
Next Steps
Explore (photos, videos, links, polls)
Dive into and upload workflows
Learn about (drafts, recurring posts)
For full API details, see the .
For assistance, contact .
Content Types
A comprehensive overview of all content formats you can publish via the Publer API. Each content type is specified by the type field inside the networks.[provider] object.
Supported Content Types
Network
Best Practices
Content Optimization
Test each format on a single account before scaling.
Use network-specific overrides to tailor text length, captions, and metadata.
Always provide alt_text for images to enhance accessibility.
Technical Considerations
Preprocess media (resize, compress) before upload to meet platform requirements.
Verify media upload success before referencing media IDs in your post payload.
Review provider documentation for specific limits (e.g., LinkedIn document size, TikTok clip length).
Related Topics
- Detailed guide for uploading and managing media
- Platform-specific capabilities and limitations
- Ways to publish different content types
Polls
Create and schedule interactive polls on LinkedIn, Mastodon, and Twitter to engage your audience and gather feedback.
Key Features
Cross-Platform Polls: One payload to post polls on multiple networks
LinkedIn PDF Carousels
Turn multiple images or documents into a scrollable PDF carousel in a single LinkedIn post. Perfect for presentations, portfolios, and multi-page documents.
Overview
Include type: "photo" and set details.type: "document" to bundle your media into a PDF carousel. You may upload images, PDFs, Word, or PowerPoint files up to 100 pages/photos.
Rate Limits
To keep our service reliable and fair, the Publer API enforces rate limits on all requests. Limits are applied per user account (across all API keys) and use a fixed-window algorithm.
Default Limits
Limit Window
Requests Allowed
Photo Posts
Visual content that drives engagement across social networks. Use photo posts to share high-quality images—single or multiple—while respecting each platform’s unique requirements.
Key Features
Multi-Platform Publishing
Post images simultaneously to all supported networks.
Twitter/X Community Posts
Publish posts directly to Twitter/X Communities using the Publer API. This feature enables you to reach targeted audiences and participate in focused discussions within X Communities—right from your own app or workflow.
Overview
Twitter/X Communities are spaces for people to connect, share, and discuss specific topics. Posts made in a Community are visible to anyone on X, but only Community members can engage (like, reply, etc.) with them.
Media Options
Manage and retrieve Facebook albums, Pinterest boards, and saved watermarks for your social accounts—all within your workspace. Use these options to organize content and protect your creative assets.
Overview
Media options help you:
Post with Location
Tag your posts with a real-world location to increase engagement and reach more local audiences. Publer supports location tagging for Facebook Pages, Instagram Business accounts and Threads accounts.
Overview
Location tagging attaches a physical place (such as a city, office, or venue) to your Facebook, Instagram or Threads post. This is especially helpful for businesses, events, and local marketing.
Members
The Members endpoint returns posting activity and engagement metrics per workspace member, optionally scoped to a single account and time range. Use it to build leaderboards, performance reviews, and workload reports.
Requirements
Authentication: Bearer API token
Scope:analyticsHeaders:
curl -X POST "https://app.publer.com/api/v1/posts/schedule" \
-H "Authorization: Bearer-API YOUR_API_KEY" \
-H "Publer-Workspace-Id: 5f8d7a62c9e77e001f36e3a1" \
-H "Content-Type: application/json" \
-d '{
"bulk": {
"state": "scheduled",
"posts": [
{
"networks": {
// You need to provide the network provider as the key, e.g., facebook, twitter
"facebook": {
"type": "status", // Type of the post
"text": "Status Update Post" // Text of the post
}
},
"accounts": [
{
"id": "63c675b54e299e9cf2b667ea", // Id of the selected account
"scheduled_at": "2025-09-06T14:16+02:00" // Scheduled time
}
]
}
]
}
}'
{
"status": "complete",
"payload": {
"failures": {}
},
"plan": {
// other account-specific data
}
}
{
"status": "complete",
"payload": {
"failures":[
{
"account_id": "63c675b54e299e9cf2b667ea",
"account_name": "Test Page",
"provider": "facebook",
"message": "There's another post at this time. A one minute gap is required between posts"
}
]
},
"plan": {
// other account-specific data
}
}
When you reach the rate limits, every API response includes these headers so you can monitor your rate limit status:
Header
Description
X-RateLimit-Limit
Total requests allowed in the current window
X-RateLimit-Remaining
Requests remaining in the current time window
X-RateLimit-Reset
UNIX timestamp when your window resets (next available slot)
Example Response Headers
When You Exceed the Limit
If you go over your quota, the API returns:
HTTP Status: 429 Too Many Requests
Response Body:
Headers will show X-RateLimit-Remaining: 0 and a future X-RateLimit-Reset.
Daily Post Limits
While most social networks don't explicitly limit daily posts, Publer implements posting limits to prevent spam, ensure compliance with platform guidelines, and allocate resources fairly. These limits are calculated on a rolling 24-hour basis in UTC timezone.
Post Limits by Plan
Platform
Free Plan
Professional Plan
Business Plan
Facebook Posts & Reels
12 / day / profile
24 / day / profile
36 / day / profile
Facebook Stories
12
24
36
Instagram Posts & Reels
15
20
Important Notes
Rolling 24-hour window: Limits are calculated based on the previous 24 hours from the current time (UTC)
Per profile/account: Facebook limits apply per connected profile or page
Anti-spam protection: These limits help maintain a balance between automation and spam prevention
Platform compliance: Limits align with each social network's community guidelines
Best Practices to Avoid Throttling
Cache responses for idempotent or infrequently changing endpoints.
Use bulk endpoints (e.g., POST /api/v1/posts/schedule for multiple posts).
Stagger non-urgent requests during off-peak hours.
Monitor headers and throttle your client.
Implement exponential backoff when you approach or hit the limit.
Requesting Higher Limits
For integrations requiring a higher rate limit, please contact us with:
Your expected request volume (per minute/hour/day)
Note: Inserting Alt text is supported on Publer for all social networks. However, when creating multi-photo posts on Facebook, adding Alt text will also count as the photo caption.
Note: You cannot add Alt text to Facebook Personal Profiles/Groups posts, due to API limitations from the networks.
Request Structure
Below is an example showing a photo post scheduled for multiple platforms.
Protect your images and videos with custom watermarks.
Retrieve all available albums/boards and watermarks per account to use in your post scheduling workflows.
Fetch Media Options
Use the following endpoint to list all available albums (for Facebook), boards (for Pinterest), and saved watermarks for the accounts in your workspace.
Parameters
Field
Type
Description
id
string
Account ID
albums
array
List of albums (Facebook) or boards (Pinterest)
albums[].id
string
Album or board ID
albums[].name
string
Album or board name
How to Use Media Options
Facebook Albums: Select an album ID when posting to Facebook to keep your photos organized and easy to browse.
Pinterest Boards: Use the board ID to specify where your Pin should be published.
Watermarks: Choose a watermark ID to apply a logo, copyright, or brand mark to your images/videos. Watermarks help deter unauthorized use and reinforce your brand.
Main post text (the signature is appended to this on publish)
Auto-Scheduling
Automatically pick the optimal posting time for your content within a specified date window. Publer analyzes your posting schedule and audience engagement to fill gaps and maximize reach.
Endpoint
Request Headers
Header
Required
Description
Request Body
Set auto: true and define range to enable auto-scheduling:
Key Parameters
Field
Type
Description
Examples
Basic Auto-Scheduling
Next Available Slot
Omit end_date and set share_next to schedule at the next open slot:
How It Works
Analyze Schedule: Publer looks at your existing posting queue and calendar.
Identify Slots: Finds open time slots based on your account’s posting schedule.
Optimize: Uses audience engagement data to pick a high-impact time within your range.
Use Cases
Fill Gaps: Keep your queue full without manual scheduling.
Engagement Boost: Leverage data-driven timing for better reach.
Bulk Campaigns: Auto-schedule large batches within a window.
Best Practices
Define Posting Schedule: Ensure your account has active time slots configured.
Reasonable Ranges: Provide a wide enough window for better slot selection.
Mix Methods: Combine auto-scheduling with manual posts for flexibility.
Common Issues
Issue
Solution
Related Topics
Multi-Link Posts (Facebook Carousels)
Create and schedule multi‐link carousel posts on Facebook Pages. Carousels let you showcase up to 10 clickable cards—each with its own image, title, description, and call-to-action—in a single organic post.
Request Body
Parameters
networks.facebook
Field
Type
Description
sublinks[] Object
Field
Type
Description
Key Notes & Limitations
Pages Only: Supported on Facebook Pages. Group posts will include only the first sublink.
Max Sublinks: Up to 10 cards per carousel.
No Cost: Carousel posts are organic (no ad spend).
Workflow
Select Page
Choose a Facebook Page account in the accounts array.
Define Sublinks
Provide url, title, description, and images for each card.
Best Practices
Engaging Thumbnails
Use high-quality images that clearly represent each link.
Clear Titles & Descriptions
Keep text concise and action-oriented to drive clicks.
Focused Carousels
Limit to 5–7 cards to avoid overwhelming users.
Related Topics
Charts
The Analytics section provide access to social media analytics data for connected accounts in your workspace. These endpoints allow you to retrieve available charts and their corresponding data for various social media platforms.
The Charts endpoints let you:
Discover which analytics charts are available (and their IDs).
Fetch time‑series and comparative data for selected charts.
Use the returned id values from “List Charts” with “Get Chart Data” to build dashboards and reports.
Requirements
Authentication: Bearer API token
Scope:analyticsHeaders:
Authorization: Bearer-API YOUR_API_KEY
Publer-Workspace-Id: YOUR_WORKSPACE_ID
Endpoints
1. List Charts
Retrieve chart definitions.
Description
Returns a list of charts grouped by category (growth, insights, demographics). Different platforms expose different charts.
Fetch data for one or more charts by ID. Returns current and previous period blocks for comparison.
Description
Supports growth metrics, post insights, and demographics. Chart IDs must come from the “List Charts” endpoint.
For better performance and lower latency, request chart data in small logical batches of related chart_ids (e.g., growth first, then insights, then demographics) instead of sending every available chart ID in one call.
URL Parameters
Parameter
Type
Required
Description
Query Parameters
Parameter
Type
Required
Description
Structure
Key
Description
Usage Notes
Always fetch chart IDs from /api/v1/analytics/charts; charts can change over time.
If account_id is omitted, results are aggregated across accessible accounts (where the metric supports aggregation).
The comparison (previous) window automatically matches the current window length.
Related Resources
- Manage social media accounts
— Track hashtag performance
— Suggested posting time slots
GIF Posts
Animated GIFs are a fun, engaging way to capture attention. Use the Publer API to create or schedule single‐GIF posts with caption and thumbnail support across multiple platforms.
Overview
GIF posts let you share looping animations with optional captions and metadata. Perfect for reactions, announcements, or adding personality to your feed.
Key Features
Cross-Platform GIF Publishing
Custom Caption Support
Thumbnail Preview
Immediate or Scheduled Posting
Platform Support & Limits
Network
Size Limit
Notes
Request Structure
Send to the scheduling endpoint (/posts/schedule) or immediate‐publish (/posts/schedule/publish):
Required Parameters
Field
Description
Workflow
Reference or upload your GIF via the .
Build your post object with "type": "gif".
(Optional) Add "thumbnail" and "name" for preview.
Best Practices
Compress GIFs to meet platform size limits without sacrificing quality.
Provide a clear, engaging thumbnail to boost click-through.
Use concise captions to add context or calls-to-action.
Related Topics
Post with Watermark
Protect your creative content and reinforce your brand by automatically applying watermarks to photos and videos you share across your social accounts.
Overview
A watermark is a logo or symbol placed on your media to discourage unauthorized use and promote your brand. With Publer, you can save, manage, and apply unique watermarks per account—no editing skills required.
Watermarking is available on the Professional Plan for images and the Business Plan for videos.
Step 1: Fetch Available Watermarks
Use the to get all saved watermarks for your account(s):
Response Example:
Each watermark is account-specific.
You can create and manage multiple watermarks per account in Publer.
Step 2: Schedule or Publish a Post with a Watermark
When creating or scheduling a post, specify the full watermark object in the relevant accounts array. The watermark settings will be applied to all attached media.
Example Request:
Parameters
Field
Type
Description
Best Practices
Use PNG logos with transparent backgrounds for cleaner results.
Place watermarks in corners with moderate opacity to protect without distracting.
Watermarking is available per account and per post—choose the right watermark for each audience.
Key Notes & Limitations
Plan Requirements: Watermarking images requires the Professional Plan, videos require the Business Plan.
Unlimited Media: No limit on the number of photos you can watermark per post.
Account-specific: Watermarks are managed and applied per account.
Related Topics
Text Posts
Simple yet powerful status updates without media attachments. Text posts are widely supported, versatile, and often drive high engagement.
Overview
Text posts (status updates) let you share plain-text messages across all major social networks. With the Publer API you can:
Publish or schedule text updates simultaneously to multiple platforms
Customize each network’s copy to match character limits and conventions
Cross-Platform Publishing
Send consistent or tailored copy to every network in one API call.
Character Limit Handling
Automatic enforcement of each platform’s text length.
Rich Text Support
Use hashtags, emojis, and markdown styling where supported.
Platform Support & Limitations
Request Structure
Below is an example showing a text post scheduled for multiple platforms:
Required Parameters
Field
Description
Best Practices
Optimize per Platform
Tailor messaging length and tone: concise on Twitter, detailed on LinkedIn.
Use Hashtags Strategically
Add relevant tags to boost discoverability; match platform conventions.
Schedule for Peak Times
Publish when your audience is most active across time zones.
Related Topics
Posts
The Posts API lets you list, filter, and inspect social media posts across your connected accounts. Build dashboards, content calendars, or analytics by combining powerful query parameters.
Requirements
Authentication: Bearer API token
Competitor Analysis
Use the Competitor Analysis endpoints to list competitor accounts and fetch their high‑level analytics (followers, growth, engagement, reach, and posting mix). Combine with Post Insights and Best Times to build a full competitive benchmarking view.
Requirements
Authentication: Bearer API token
Scope:analytics Headers:
Pinterest Pins With a Link URL
Share visually engaging Pins with an external link URL to drive traffic from Pinterest boards.
Overview
Create or schedule a Pinterest Pin by setting type: "photo", adding your media, specifying url for the external link, and the album_id to select the destination board.
Immediate Publishing
Publish content to social networks instantly using the Publer API. This method skips scheduling and sends posts for immediate delivery.
Dynamic, high-impact video content for social networks. Video posts drive significantly more views and shares than static media, and the Publer API makes it easy to upload, configure, and schedule videos across multiple platforms.
Overview
Programmatically create and schedule video content—standard uploads, short-form (Reels/Shorts/Stories), and rich metadata (titles, descriptions, custom thumbnails)—while meeting each network’s format rules and size limits.
Key Capabilities
Cross-Platform Publishing
One API call to distribute videos to Facebook, Instagram, YouTube, TikTok, LinkedIn, and more.
Format Versatility
Support for standard videos, short-form (Reels, Shorts), and Stories.
Rich Metadata
Attach titles, captions, and custom thumbnail selections.
Platform Support & Specifications
Network
Video Types
Duration
Size Limit
Aspect Ratio
Additional Features
Request Structure
Schedule a video post using the unified scheduling endpoint:
Required Parameters
Field
Description
* Optional if you publish immediately via /posts/schedule/publish.
Workflow for Creating Video Posts
Upload Video
Use the endpoint to upload your video.
Receive Media ID
Note the returned id for referencing in your post payload.
Configure Thumbnails
Upload or select thumbnail images and include their IDs/URLs.
Best Practices
Select Engaging Thumbnails
Choose a frame or custom image that drives clicks.
Provide Clear Titles & Descriptions
Improve accessibility and SEO with detailed metadata.
Validate Platform Requirements
Confirm aspect ratio, encoding, and file format (MP4/H.264 recommended).
Related Topics
Bulk Scheduling
Efficiently schedule up to 500 posts across multiple accounts and networks in a single API request. Bulk scheduling in Publer streamlines content planning and helps you stay organized at scale.
Overview
Bulk scheduling lets you prepare, customize, and schedule a large number of posts at once—supporting both text and media content for all supported networks. Each post in the bulk payload can have unique content, network targeting, and scheduling options.
Key Features
Create and schedule up to 500 posts in a single API call.
Combine multiple social accounts and networks per post.
Supports text, images, videos, and more.
Request Structure
Send a POST request to the scheduling endpoint with your bulk payload:
Endpoint
Request Headers
Header
Required
Description
Request Body
Example Payload:
Parameters
Field
Type
Description
Scheduling Modes
Schedule:
Add scheduled_at to specify exact publish time per account/post.
Auto Schedule:
Omit scheduled_at and set bulk.state to "auto" to use the account's posting schedule.
How It Works
Prepare Your Bulk Payload:
List each post with its content, targeted networks, and accounts.
Customize Each Post:
Add media, captions, hashtags, locations, watermarks, and more individually per post.
Choose Scheduling Mode:
Use scheduled_at for manual scheduling or let Publer auto-schedule based on your rules.
Best Practices
Use bulk scheduling for campaigns, product launches, or large-scale social content plans.
Individually tailor each post for its platform and audience.
Use the scheduling modes for flexibility—manual times for some posts, auto-schedule for others.
Related Topics
Recycling Posts
Automatically re-share a post on a regular cadence. Recycling is ideal for evergreen content, reminders, and promotional campaigns.
Endpoint
Request Headers
Header
Required
Description
Request Body
Include a recycling object in your payload:
Recycling Parameters
Field
Type
Description
Examples
Basic Recycling
Recycle every 2 weeks, up to 3 times:
Recycling with Expiration Date
Recycle monthly until end of year:
How It Works
Create a post with recycling settings.
Publer queues the post for reuse.
After each gap interval, the post is republished.
Platform Limitations
Due to API limitations and anti-spam policies, recycling has some platform-specific constraints:
Use Cases
Promote evergreen blog posts or resources.
Remind followers of ongoing events or offers.
Keep your feed active with minimal manual effort.
Best Practices
Vary content slightly using Spintax to avoid spam filters.
Choose sensible intervals—don’t recycle too frequently.
Always set an expiration (expire_count or expire_date).
Recycling vs. Recurring
Recycling fills open slots based on gap and gap_freq—ideal for evergreen content.
Recurring publishes at exact times on a fixed repeat schedule (e.g., every Monday at 9 AM).
Related Topics
Hashtag Analysis
The Hashtag Analysis endpoints help you understand how hashtags perform across your workspace or a specific account. Use them to rank, filter, and retrieve top posts for any hashtag.
Requirements
Authentication: Bearer API token
Scope:analyticsHeaders:
Authorization: Bearer-API YOUR_API_KEY
Publer-Workspace-Id: YOUR_WORKSPACE_ID
Endpoints
1. Get Hashtag Insights
Retrieve aggregated analytics for hashtags used in published posts. Supports filtering by date range, account, member, and search, plus sorting and pagination.
Description
Returns a paginated list of hashtags with totals for posts, reach, engagement, and related metrics, plus up to 3 recent posts per hashtag and a hashtag performance score.
URL Parameter
Parameter
Type
Required
Description
Query Parameters
Param
Type
Required
Description
Fields:
records[]: One row per hashtag.
hashtag: Text without #.
2. Get Hashtag Performing Posts
Retrieve up to 6 top posts that used a specific hashtag, with full per‑post analytics.
URL Parameter
Parameter
Type
Required
Description
Query Parameters
Param
Type
Required
Description
Notes
Time range: Defaults to the workspace’s default range when not provided. “Last X Days” excludes partial data for the current day.
Sorting & ranking: Use sort_by and sort_type to rank by Posts, Reach, Reactions (likes), Comments, Shares, or Video Views. UI columns can be reordered client‑side.
Data freshness: Insights auto‑refresh every ~24h; you can manually sync in the UI for real‑time updates.
Related Resources
— Per‑post performance analytics
— Discover chart IDs and fetch chart data
— Suggested posting time slots
Link Posts
Share URLs with rich previews (title, description, image, and call-to-action) across your social networks via the Publer API.
Overview
Link posts display a URL preview alongside optional caption text. You control metadata (title, description, images, CTA) to enhance engagement.
Before scheduling a link post, you can extract rich metadata from any URL using the /posts/links endpoint. This step is optional but highly recommended for accurate previews.
Use this extracted metadata to build your link post payload.
Step 2: Create or Schedule a Link Post
Use the unified scheduling endpoint (/posts/schedule) or the immediate-publish endpoint (/posts/schedule/publish):
Parameters
Field
Type
Description
Note: You can also include original_title, original_description, and original_images if you pre‐fetch metadata yourself, but only the link.* fields above are required.
Workflow
Extract Metadata
Use /posts/links to fetch title, description, and images from your target URL.
Compose Metadata
Define url, title, description, and images in the link
Best Practices
Provide Complete Metadata: Supply title, description, and images for compelling previews.
Optimize Image Dimensions: Match each network’s recommended preview size for best display.
Use Clear CTAs: Select a relevant call_to_action to guide user action.
Related Topics
Post Insights
The Post Insights endpoint retrieves detailed performance analytics for published posts, with powerful filtering, sorting, and pagination. Use it to build per-post dashboards, leaderboards, and competitor comparisons.
Requirements
Authentication: Bearer API token
Scope:analyticsHeaders:
Authorization: Bearer-API YOUR_API_KEY
Publer-Workspace-Id: YOUR_WORKSPACE_ID
Endpoint
Get Post Insights
Retrieve comprehensive analytics for posts within a workspace or a specific social account. Supports competitor analysis, text search, labels, post types, date ranges, member filtering, and multiple sort options.
Description
When :account_id is a specific social account ID, results are limited to that account.
When :account_id is omitted, results include all accessible accounts.
Enable competitor mode with competitors=true
URL Parameter
Parameter
Type
Required
Description
Query Parameters
Parameter
Type
Required
Description
Notes
Data sources: Metrics come from the official social network APIs. Insights auto‑sync periodically; you can manually sync in the UI for fresher data.
Post vs aggregate reach: Post Insights show reach per post. Charts/overview may show total reach across all posts for a time window, so numbers won’t necessarily sum 1:1.
Engagement formula: Typically the sum of likes/reactions + comments + shares + saves + post clicks (platform‑dependent).
Related Resources
— Discover chart IDs and fetch chart data
— Track hashtag performance
— Suggested posting time slots
Updating Posts
Modify an existing post—whether scheduled or already published—across your social networks. This endpoint handles network-specific constraints and supports advanced features like recycling and recurring schedules.
Requirements
Authentication: Bearer API token
Scope: posts
Headers:
Authorization: Bearer-API YOUR_API_KEY
Publer-Workspace-Id: YOUR_WORKSPACE_ID
Endpoint
Updates an existing post by ID. The behavior differs depending on whether the post is scheduled or already published.
Parameter Reference
Special Cases
When the post is published, you can only update network-specific params.
Networks Not Supporting Published Post Updates
For the following networks, only labels can be updated in Publer's database after a post is published:
Twitter/X (polls cannot be edited after publishing)
Pinterest
Instagram
Threads
Recurring Posts
If the post is a recurring post, the update will be applied to all future child posts in the recurring series. Already published child posts will not be affected.
Notes
When updating a post that requires approval, a notification will be sent to the appropriate workspace members.
Changes to published posts will be reflected both in Publer's database and on the social media platform (for supported networks).
Related Resources
- Retrieve and filter posts
- Manage social media accounts
- Upload and manage media for posts
Recurring Posts
Automatically publish the same post at regular intervals, indefinitely or until a specified stop condition.
Endpoint
Request Headers
Google Business Profiles: Updates, Photos, Events & Offers
Share updates, photos, events, and special offers on your Google Business Profile via the Publer API. Each post type has its own fields—use the right payload to drive engagement and conversions.
Ensure the connected accounts have immediate-posting permissions.
Optionally add alt_text.
.
networks.pinterest.media[].path
string
URL to the full-size image or video.
networks.pinterest.media[].thumbnail
string
URL to the thumbnail image.
networks.pinterest.media[].type
string
Must be "photo" or "video".
networks.pinterest.media[].alt_text
string
Accessible description of the image (optional).
networks.pinterest.title
string
Pin title displayed on hover.
networks.pinterest.url
string
Clickable external link URL.
accounts[].id
string
Pinterest account identifier.
accounts[].album_id
string
Board ID where the Pin will be posted.
accounts[].scheduled_at
string
ISO 8601 timestamp for scheduling (omit to publish immediately).
Advanced Scheduling
Schedule per time zone or publish immediately; poll job status for completion.
1.91:1–4:5 (feed)
9:16 (Reels/Stories)
Location tagging, first comment
YouTube
Standard, Shorts
Standard: up to 12 h
Shorts: up to 3 min
< 2 GB
16:9 (standard)
9:16 (Shorts)
Custom thumbnails, tags, categories
TikTok
Standard
3 s–10 min
< 2 GB
9:16 (recommended)
Sound attribution
LinkedIn
Standard
3 s–15 min
< 2 GB
1:2.4–2.4:1
Native profile/page posting
Pinterest
Standard
4 s–15 min
< 2 GB
—
—
Twitter/X
Standard
Up to 10 min
< 512 MB
Flexible
Alt text support
Telegram
Standard
Unlimited
< 50 MB
Flexible
—
Mastodon
Standard
Unlimited
< 40 MB
Up to 1920×1200 px
—
Threads
Standard
Up to 5 min
< 1 GB
Flexible
—
Bluesky
Standard
Up to 3 min
< 50 MB
Flexible
—
networks.{provider}.text
Optional caption or description.
accounts[].id
Target social media account ID.
accounts[].scheduled_at*
ISO 8601 timestamp (omit for immediate publishing).
Compose & Schedule
Build your post object, set state and scheduled_at, then send to /posts/schedule.
Monitor Job
Poll /api/v1/job_status/{job_id} until status is completed.
Facebook
Standard, Reels, Story
Standard: up to 5 h
Reels: 3–90 s
Stories: ≤60 s
< 2 GB
Flexible
Auto-captions, premiere scheduling
Instagram
Feed, Reels, Story
Feed: any
Reels: 3 s–15 min
Stories: ≤60 s
bulk.state
Must be "scheduled".
networks.{provider}.type
Set to "video".
networks.{provider}.media
Array of video metadata objects.
networks.{provider}.media[].id
ID returned by the Media Upload endpoint.
networks.{provider}.media[].thumbnails
Array of thumbnail objects with id, small, and real URLs. To add a custom thumbnail, append an object with small and real. Always fetch the full thumbnails array, either from Listing Media or from Media Upload, when uploading.
Platform differences: Not all metrics are available for all networks or account types (e.g., LinkedIn Profiles vs Pages).
Pagination: Use page (0‑based). Each page returns 10 posts. Response includes total to compute more pages.
Competitors: Requires competitors=true. Use competitor_id to focus on a single competitor’s posts; otherwise data may include multiple competitors (if enabled).
The Posts Create endpoints let you asynchronously schedule, draft, or immediately publish content across one or more social networks. Submit a batch request, receive a job ID, then poll for completion.
Requirements
Authentication: Bearer API token
GET /api/v1/analytics/:account_id/hashtag_insights
GET /api/v1/analytics/hashtag_performing_posts
{
"bulk": {
"state": "scheduled",
"posts": [
{
"networks": {
"facebook": {
"type": "link",
"text": "This is the link post type",
"link": {
"url": "http://publer.com",
"provider_display": "publer.com",
"description": "Boost your social media strategy with Publer’s suite of tools. Manage multiple accounts, schedule posts, collaborate with your team, and analyze performance—all in one place.",
"title": "Powerful Social Media Management & Scheduling Tools | Publer",
"images": [
"https://framerusercontent.com/assets/20xDElBhD9Xg3L7Cx7jVMwL56FU.png",
"https://framerusercontent.com/images/OVMI4DbyRxf9neKFkqKesfnSlHE.png",
"https://framerusercontent.com/images/ShxTAH03BsTSB29AeYZzpPZqi8.jpg",
"https://framerusercontent.com/images/iuLpS9a0syZanung3ZFGrbYXTKM.jpg",
"https://framerusercontent.com/images/d7Gg6Hvachd0DuRzXGKoB1szAl4.jpg"
],
"default_image": 0,
"call_to_action": "LEARN_MORE",
"phone_number": ""
}
}
},
"accounts": [
{
"id": "63c675b54e299e9cf2b667ea",
"scheduled_at": "2025-05-24T23:18+02:00"
}
]
}
]
}
}
Content Types: Detailed guide to content formats and requirements
Media Handling: Information about uploading and managing media
: Platform-specific capabilities and limitations
Ideas
What are Ideas?
Ideas are unfinished posts or content templates that aren’t linked to any specific social account yet. You can create them, work on them over time, collaborate with your team, and turn them into real posts whenever you’re ready.
Idea States
draft_public: visible to the entire workspace and editable by teammates (based on permissions)
draft_private: visible only to the creator
Endpoint
Ideas are created using the same bulk scheduling endpoint, but with an Idea state and no social accounts.
Request Headers
Header
Required
Value
Rules / Requirements
bulk.state must be draft_public or draft_private
Use networks.default
Rich content mode: Content blocks format
When using type: "article", content must be an array of blocks:
id: randomly generated string
type: one of the supported block types
data: object depending on block type
Example: Create an Idea (Public) — Rich Content (article)
Example: Create an Idea from a Simple Type (Auto-converted)
You can also create an Idea using other (for example status, photo, video, link). Publer will convert the payload into the Idea content format automatically (including tags).
Media Attachments (Ideas)
You can attach media to an Idea using networks.default.media.
Notes
media is an array.
Multiple attachments are supported for photos only.
Supported media types include photo and video
To attach media, first fetch/upload media using the or , then reference the returned media objects in your payload.
Parameters
Bulk
Field
Type
Required
Description
Post Object (Idea)
Field
Type
Required
Description
Network Configuration
For Ideas (draft_public, draft_private):
Use default as the network key.
You can send either:
Rich content: type: "article" with title
Best Practices
Save ideas early to avoid losing inspiration.
Use draft_public for collaboration and feedback.
Use draft_private for personal planning.
Related Topics
Media Handling
Manage your media assets before attaching them to posts. Publer’s API supports direct uploads and URL imports, returning media IDs you can reference when creating or updating posts.
Overview
Before including media in your social media posts, you must first upload those files to Publer's servers. The API provides two methods for uploading media:
Direct file upload
Upload from URL
Once uploaded, you'll receive a media ID that can be referenced in your post requests.
Direct File Upload
Use this method when you have local media files that you want to upload directly.
Limitation
Maximum file size for direct uploads: 200MB per file.
Requests exceeding 200MB will be rejected (typically with HTTP 413 Payload Too Large). For larger files, use the method.
Request Format
This endpoint expects a multipart/form-data request with the file included in the file field.
Key Response Fields
Upload from URL
Use this method when your media is already hosted elsewhere and you want to import it by URL.
Request Parameters
Unlike direct uploads, URL uploads are processed asynchronously. Use the returned job_id to check the status of your upload.
Checking Upload Status
Using Media in Posts
Once you've uploaded media and have the media ID, you can reference it in your post requests:
Supported Media Types
Images
Supported formats: JPG, PNG, GIF, WEBP
Recommended dimensions: Varies by platform (see )
Maximum file size: Varies by platform, generally 5-10MB
Videos
Supported formats: MP4, MOV, AVI, WEBM
Recommended dimensions: Varies by platform (see )
Maximum file size: Varies by platform, generally 512MB-2GB
Documents
Supported formats: PDF
Maximum file size: 100MB
Supported networks: LinkedIn only
Network Validation
The validity object in the media upload response indicates which networks and post types can use the uploaded media. This helps prevent errors when attempting to use incompatible media in your posts.
For example, if validity.instagram.reel is false, the uploaded media cannot be used for Instagram Reels.
Best Practices
Image Optimization
Resolution: Use appropriate image resolutions for each platform
Aspect ratio: Follow recommended aspect ratios to avoid cropping
File size: Optimize images for web to reduce file size
Video Optimization
Format: Use MP4 with H.264 encoding for maximum compatibility
Dimensions: Use 1080p (1920x1080) for standard videos
Aspect ratio: 16:9 for horizontal, 9:16 for vertical/stories/reels
General Tips
Pre-check compatibility: Review the validity object before using media
Error handling: Implement robust error handling for upload failures
Caching: Cache media IDs to avoid unnecessary re-uploads
Related Topics
- Details on different content formats
- Platform-specific media requirements
- Using media in different post types
Facebook Text Posts with Background
Create and schedule Facebook status updates with vibrant backgrounds to boost engagement and visual appeal.
Request Body
Include text_format_preset_id in details under the facebook network:
Submit Request → Receive Job ID → Poll Job Status → Processing Complete
Rich content mode (recommended): type = "article" with title, content blocks, and optional media
Simple content types: you can also submit status, photo, video, or link payloads; Publer will convert them automatically into the Idea content format (with tags) behind the scenes
At least one of title, content, or media must be present (for type: "article")
(see network/provider specifics).
posts[].networks.default.content
array
Conditional
Used with type: "article"
posts[].networks.default.text
string
Conditional
Used with type: "status" (and other simple types as applicable)
posts[].networks.default.media
array
No
Media attachments
,
content
, and optional
media
, or
Simple types (e.g., status, photo, video, link) which are auto-converted into the Idea content format.
Publish or schedule TikTok videos and multi-photo (carousel) posts using the Publer API. This feature supports all TikTok-specific options, including privacy, comments, branded content, and more.
Overview
Publer enables you to directly post or schedule TikTok videos and multi-photo posts (carousels) from your app or workflow.
You can only post to one TikTok account at a time—TikTok does not allow duplicate content or posting to multiple accounts simultaneously.
Video posts: Upload and schedule single video posts. Supports cover selection, privacy, comment/duet/stitch toggles, and branded content disclosures.
Multi-photo posts (carousels): Upload and schedule up to 35 photos, each with an optional caption, as a single post. Supports music auto-add, privacy, and engagement options.
Notice: TikTok Video Publishing & Link Availability
When posting a video to TikTok, the API does not immediately return a URL to the published post.
TikTok first processes the video after upload and only makes the public link available once processing is complete.
After posting a video:
The returned response will not contain the TikTok post URL.
To obtain the published TikTok video link:
Retrieve your post later via the .
Once TikTok finishes processing, the link will be included in the post data.
How It Works
To schedule or publish a TikTok post, use the or API endpoint with a networks.tiktok object describing your post.
Key Rules
No recurring or recycled videos: TikTok does not allow duplicate content.
Watermarks: Not supported due to TikTok API limits.
Privacy and engagement: Options are synced from TikTok and may vary by account type, check your account details from .
Video Post Example
Multi-Photo Post (Carousel) Example
TikTok-Specific Parameters
Video Post Parameters
Field
Type
Required
Description
Carousel (Multi-Photo) Post Parameters
Field
Type
Required
Description
Tips & Limitations
No GIF/video mixing: Carousel posts cannot mix photos, GIFs, or videos.
Privacy: "Everyone" is only available if the TikTok account is public.
Branded content: Cannot be private. Once posted, branded content is permanently labeled.
Related Topics
Reels, Shorts & Stories
Short-form, immersive content formats for deep engagement. Use Publer’s API to schedule or publish Reels (Instagram & Facebook), Shorts (YouTube), and Stories (Instagram & Facebook) with a single JSON payload.
Supported Formats & Specs
Format
Platform
Max Duration
Aspect Ratio
Max Size
Notes
Request Structure
Send to the scheduling endpoint or use /posts/schedule/publish for immediate posting:
1. Instagram/Facebook Reel
Instagram Trial Reels (optional)
Trial Reels let you publish a Reel as a trial before it’s shown to your followers.
Set networks.instagram.details.trial_reel when creating an Instagram Reel:
MANUALThe Reel remains in trial until you approve sharing it with your followers.
SS_PERFORMANCE: Instagram may automatically share the Reel to your followers if it performs well.
Notes
trial_reel is only supported for Instagram Reels (details.type = "reel").
trial_reel is optional. If omitted, the Reel is created normally.
trial_reel is only supported for Instagram Reels (details.type: "reel").
2. YouTube Short
3. Instagram/Facebook Story
Common Parameters
Field
Type
Description
Workflow
Reels
Upload: Use to upload vertical video (9:16).
Compose: Set "details.type": "reel", optional audio and feed flags.
Shorts
Upload: Upload video ≤ 60 sec, 9:16 ratio.
Configure: Set "details.type": "short" and privacy.
Add Title/Text: Populate title
Stories
Upload: Add photo or video ≤ 15 sec.
Tag as Story: Use "details.type": "story".
Caption: Add text overlay.
Best Practices
Use high-quality, platform-compliant media (9:16 ratio).
Rename Reel audio to match branding.
Schedule according to audience peak times.
Related Topics
Post Callbacks
Automate follow-up actions when you publish or schedule posts: auto-share to other accounts, post follow-up comments (or thread posts on some networks), or auto-delete/hide content after specified conditions are met.
Overview
Post callbacks are automation features you include per-account in the API request when creating posts. Callbacks are configured inside each accounts[] entry. The main callback types:
AutoShare — automatically share a published post to other social accounts
Follow-up Comments — schedule one or multiple comments (or threaded posts) tied to a post
Auto-Delete / Auto-Hide — automatically remove or hide posts after conditions are met
Conditions are represented with a structured conditions object (relation + clauses) and can combine Time (age), Reach and Engagements checks using AND/OR.
Endpoints
Schedule with callbacks:
POST /api/v1/posts/schedule
Publish now with callbacks:
POST /api/v1/posts/schedule/publish
Callbacks live inside each account object in your request payload.
Request structure (top-level)
bulk
state (e.g., "scheduled")
posts[]:
Conditions object
Use conditions to define when a callback should execute.
Structure:
conditions
relation: "AND" | "OR"
clauses:
Notes:
age corresponds to "Is older than".
engagements and reach use comparison with "gt" (>) or "lt" (<).
Auto-Sharing
Automatically share the link of the published post to the specified accounts.
Fields:
share.account_ids (string[]) — target account IDs to share to
share.text (string) — caption for the share (fallback: original post text where supported)
share.conditions (object) — when the share should run (see Conditions object)
Example:
Supported networks: Facebook Pages→Groups (when posting as a Page to a Group), Twitter/X, LinkedIn, Pinterest, Mastodon, Threads, BlueSky, TikTok, Telegram, Google Business Profiles.
Note: Google Business Profiles require non-empty text to auto-share.
Follow-up Comments
Schedule comments on the published post (or create follow-up posts/threads on some networks).
Fields:
comments[]:
text (string) — comment body (text, hashtags, links, emoji)
language (string, optional)
Notes and behavior:
On Twitter/X, Mastodon, BlueSky, and Threads the follow-up comment will be posted as a new post in the thread.
Not supported (API limitations): Pinterest, TikTok, Facebook Personal Profiles, Google Business Profiles.
Example:
Auto-Delete / Auto-Hide
Automatically delete or hide a post when conditions are satisfied.
Fields:
delete.conditions (object) — conditions triggering deletion/hide (see Conditions object)
Use conditions.clauses.age to set minimum time before deletion
delete.hide (boolean) — true to request hide instead of delete (platform-dependent)
Example:
Supported / unsupported:
Auto-delete supported for most scheduled networks except:
Not available for Instagram API (auto-delete not supported)
Not available for TikTok accounts
Request Structure
Full example
Best practices
Use performance-based conditions to avoid premature callbacks (e.g., only share if the post reached a threshold).
Respect audience time zones when scheduling shares and comments.
Space out repeated shares across accounts using share.delay to avoid spam signals.
Recurring posts & Post Presets
Recurring posts: add callbacks during scheduling so each recurrence includes them automatically.
Post Presets: configure default follow-up comments, auto-share targets, and default auto-delete/hide rules in Post Presets inside Publer. Presets use the same conditions model.
Limitations & notes
Some networks convert comments into separate posts/threads (Twitter/X, Mastodon, BlueSky, Threads).
Follow-up comments are not supported by Pinterest, TikTok, Facebook Personal Profiles, and Google Business Profiles due to API limitations.
Auto-delete is not available for Instagram, TikTok, posts published via reminders, or some story formats.
engagements: { comparison: "gt" | "lt", value: number }
reach: { comparison: "gt" | "lt", value: number }
A conditions object can include any subset of clauses; combine them using relation.
share.account_ids order + delay determine spacing between shares
media (object, optional):
media.id: id of the media
media.path: URL / path
media.caption (optional)
media.thumbnail (optional, videos)
conditions (object, optional) — when to post the comment (see Conditions object)
Recurring posts: Configure follow-up comments at scheduling time to have them included for each recurrence.
Performance-based conditions (reach/engagements) and time-based (age) commonly apply to the first comment; subsequent comments use time-based age only.
Not available for posts published via reminders or some push/published types
Some types (e.g., Stories) cannot be auto-deleted
Auto-hide only works where supported (e.g., Facebook Page posts (not videos), YouTube)
Prefer hiding (when supported) to preserve analytics/history if you may need them later.
Test callback behavior on target networks (APIs and behavior differ per platform).
Performance-based conditions depend on platform metrics; metrics may arrive with delay.
A concise guide to all content publishing methods available via the Publer API. Choose the method that best fits your workflow, from instant publishing to automated recycling and recurring schedules.
Available Methods
Method
Use Case
Key Parameters
Business Value
Publish content right away
No scheduled_at
Time-sensitive announcements, breaking news
Publish at specific date/time
scheduled_at
Content calendar planning, timed campaigns
Save for later use
state: draft
Workspace collaboration, content preparation
Automatically scheduling posts
auto: true
Engagement optimization, workload reduction
Reuse content multiple times
recycling object
Evergreen content, extended reach
Create repeating posts
recurring object
Regular updates, consistent presence
Immediate Publishing
Send your post to networks right away.
Endpoint:
Request example:
Implementation Notes
Omit scheduled_at entirely
Content is processed immediately via the schedule/publish endpoint
Supports all content types and network-specific options
Let Publer pick the best posting times within a date range.
Endpoint:
Before auto-scheduling, you need to keep in mind that:
You need a posting schedule. Posting schedules are account-specific. You can have only one posting schedule per account, however, it can consist of many time slots.
If you want the same posting schedule across multiple social accounts, you can do so by Duplicating Settings.
Request example:
Key Auto-Scheduling Parameters
Parameter
Type
Required
Description
auto
boolean
Yes
Set to true to enable auto-scheduling
range.start_date
string
Yes
ISO 8601 timestamp for earliest possible posting time
range.end_date
string
No
ISO 8601 timestamp for latest possible posting time
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.
Authorizations
AuthorizationstringRequired
API key authentication. Format: "Bearer-API YOUR_API_KEY"
Query parameters
post_idsstring[]Required
Array of post IDs to delete. Can include both MongoDB ObjectIDs and PostgreSQL IDs.
Header parameters
Publer-Workspace-IdstringRequired
ID of the workspace containing the posts
Responses
200
Posts deleted successfully
application/json
deleted_idsstring[]Optional
Array of IDs of successfully deleted posts
401
Unauthorized
application/json
403
Permission denied or missing required scope
application/json
delete
/posts
List Accounts
get
Retrieves a list of social media accounts available in the specified workspace.
Authorizations
AuthorizationstringRequired
API key authentication. Format: "Bearer-API YOUR_API_KEY"
Header parameters
Publer-Workspace-IdstringRequired
ID of the workspace to retrieve accounts from
Responses
200
Successful operation
application/json
idstringOptional
Unique identifier for the account
Example: 63c675b54e299e9cf2b667ea
providerstring · enumOptional
The social network provider
Example: blueskyPossible values:
namestringOptional
The display name of the social media account
Example: Tech News Daily
social_idstringOptional
Unique identifier for the account on the social media platform
Retrieves the optimal posting times for a specific social media account based on historical analytics data. Returns a heatmap of posting performance across days of the week and hours of the day, tailored to the specified account's audience engagement patterns.
Authorizations
Path parameters
account_idstringOptional
Social media account ID to analyze posting times for. When provided, analysis is specific to this account's performance data
Query parameters
competitorsstring · enumOptional
Include competitor data in best times analysis. Set to 'true' to analyze competitor posting patterns
Possible values:
competitor_idstringOptional
Specific competitor ID to analyze. Used in conjunction with competitors=true parameter
fromstring · dateRequired
Start date for analytics data range (YYYY-MM-DD format). Filters data from this date onwards
Example: {"value":"2024-01-01"}
tostring · dateRequired
End date for analytics data range (YYYY-MM-DD format). Filters data up to this date
Example: {"value":"2024-12-31"}
Header parameters
Publer-Workspace-IdstringRequired
ID of the workspace to retrieve best times from
Responses
200
Best times to post data organized by day of the week and hour for the specific account
application/json
Heatmap data showing optimal posting times with scores for each hour of each day, specific to the account's audience
Other propertiesnumber[]Optional
Array of 24 hourly scores (0-23) for each day of the week
401
Unauthorized
application/json
403
Permission denied - requires analytics access or paying subscription
application/json
get
/analytics/{account_id}/best_times
Get Signatures for Accounts
get
Retrieves signatures associated with specified accounts in a workspace.
Authorizations
AuthorizationstringRequired
API key authentication. Format: "Bearer-API YOUR_API_KEY"
Path parameters
workspace_idstringRequired
ID of the workspace to retrieve signatures from
Query parameters
accountsstring[]Required
Array of account IDs to filter signatures by
Responses
200
Successful operation
application/json
account_idstringOptional
ID of the account
401
Unauthorized
application/json
403
Permission denied or missing required scope
application/json
get
/workspaces/{workspace_id}/signatures
List Media
get
Retrieves a paginated list of media items from the user's library. The endpoint supports filtering by various parameters and can also retrieve specific media items by their IDs.
Authorizations
AuthorizationstringRequired
API key authentication. Format: "Bearer-API YOUR_API_KEY"
Query parameters
idsstring[]Optional
Specific media IDs to retrieve. If provided, pagination and other filters are ignored
pageintegerOptional
Page number for pagination (0-based)
usedboolean[]Required
Filter by used status
searchstringOptional
Search term to filter media by name or caption
Header parameters
Publer-Workspace-IdstringRequired
ID of the workspace to retrieve media from
Responses
200
Successful operation
application/json
totalintegerOptional
Total count of media items matching the query (without pagination)
Example: 10
401
Unauthorized
application/json
403
Permission denied or missing required scope
application/json
get
/media
Get Media Options
get
Retrieves albums and watermarks for specified accounts in a workspace.
Authorizations
AuthorizationstringRequired
API key authentication. Format: "Bearer-API YOUR_API_KEY"
Path parameters
workspace_idstringRequired
ID of the workspace to retrieve media options from
Query parameters
accountsstring[]Required
Array of account IDs to filter media options by
Responses
200
Successful operation
application/json
idstringOptional
401
Unauthorized
application/json
403
Permission denied
application/json
get
/workspaces/{workspace_id}/media_options
Search for Facebook locations
get
Search and retrieve Facebook locations based on a query string.
Authorizations
Query parameters
qstringRequired
Search query for Facebook locations
Responses
200
List of Facebook locations matching the search query
application/json
idstringRequired
Unique identifier of the location
namestringRequired
Name of the location
infostringOptional
Additional information about the location
Example: Main office in New York City ⋅ 1,030 follow this
verifiedbooleanOptional
Whether the location is verified
Example: true
403
Authentication failure or invalid token
application/json
422
Invalid request or Facebook API error
application/json
get
/locations/facebook
Search for Instagram locations
get
Search and retrieve Instagram locations based on a query string.
Authorizations
Query parameters
qstringRequired
Search query for Instagram locations
Responses
200
List of Instagram locations matching the search query
application/json
idstringRequired
Unique identifier of the location
namestringRequired
Name of the location
infostringOptional
Additional information about the location
Example: Main office in New York City ⋅ 1,030 follow this
verifiedbooleanOptional
Whether the location is verified
Example: true
403
Authentication failure, invalid token, or no Instagram account with Facebook login
application/json
422
Invalid request or Instagram API error
application/json
get
/locations/instagram
Search for Threads locations
get
Search and retrieve Threads locations based on a query string.
Authorizations
Query parameters
qstringRequired
Search query for Threads locations
Responses
200
List of Threads locations matching the search query
application/json
idstringRequired
Unique identifier of the location
namestringRequired
Name of the location
infostringOptional
Additional information about the location
Example: Main office in New York City
403
Authentication failure, invalid token, or no Threads account
application/json
422
Invalid request or Threads API error
application/json
get
/locations/threads
Get Analytics Members Data
get
Retrieves analytics data for workspace members showing their posting activity and engagement metrics.
Authorizations
Query parameters
fromstring · dateRequired
Start date for analytics data range (YYYY-MM-DD format). Filters data from this date onwards
Example: {"value":"2024-01-01"}
tostring · dateRequired
End date for analytics data range (YYYY-MM-DD format). Filters data up to this date
Example: {"value":"2024-12-31"}
account_idstringOptional
Optional account ID to filter analytics data for a specific social media account
Example: {"value":"63c675b54e299e9cf2b667ea"}
Header parameters
Publer-Workspace-IdstringRequired
ID of the workspace to retrieve members from
Responses
200
Members analytics data with performance metrics
application/json
List of members with their analytics data
engagementsintegerOptional
Total engagements (likes + comments + shares + post clicks) for the member
Example: 1250
postsintegerOptional
Total number of posts created by the member
Example: 42
reachintegerOptional
Total reach for the member's posts (only included for supported account types)
Permission denied - requires analytics access or paying subscription
application/json
get
/analytics/members
Get Available Analytics Charts
get
Retrieves a list of available analytics charts filtered by account type and chart type. Charts include growth metrics (followers, connections), insights (engagement, reach), and demographics (countries, ages).
Authorizations
Query parameters
account_typestring · enumOptional
Social media platform type to filter charts for (e.g., 'ig_business', 'fb_page', 'twitter', 'linkedin', 'youtube', 'tiktok', 'google', 'pin_business')
Possible values:
Header parameters
Publer-Workspace-IdstringRequired
ID of the workspace to retrieve charts from
Responses
200
List of available charts with metadata
application/json
idstringOptional
Unique identifier for the chart
Example: followers
titlestringOptional
Display title of the chart
Example: Followers
group_idstringOptional
Group category (growth, insights, demographics)
Example: growth
tooltipstringOptional
Tooltip text explaining the chart
typestring · enumOptional
Chart visualization type
Possible values:
last_valuebooleanOptional
Whether to show the most recent value
show_percentagebooleanOptional
Whether values should be displayed as percentages
401
Unauthorized
application/json
403
Permission denied or missing required scope
application/json
get
/analytics/charts
Get Analytics Chart Data
get
Retrieves analytics data for specific charts by their IDs. Returns current and previous period data for comparison. Supports growth metrics, post insights, and demographic data.
Authorizations
Path parameters
account_idstringOptional
Optional account ID to filter analytics data for a specific social media account
Query parameters
chart_idsstring[]Required
Array of chart IDs to retrieve data for. Use chart IDs from the /analytics/charts endpoint
Retrieves a list of competitor accounts for the workspace or for a specific social media account.
Authorizations
Path parameters
account_idstringOptional
ID of the social media account to retrieve competitors for.
Header parameters
Publer-Workspace-IdstringRequired
ID of the workspace to retrieve competitors from
Responses
200
Successful operation
application/json
providerstringOptional
Social media provider (instagram, facebook, twitter, etc.)
namestringOptional
Display name of the competitor account
social_idstringOptional
Unique social media ID of the competitor
picturestringOptional
Profile picture URL of the competitor
typestringOptional
Type of account (user, page, etc.)
competitor_sync_in_queuebooleanOptional
Whether competitor sync is currently queued
usernamestringOptional
Username of the competitor (available for twitter, instagram, telegram, mastodon)
verifiedbooleanOptional
Whether the account is verified (available for twitter, facebook)
401
Unauthorized
application/json
403
Permission denied or missing required scope
application/json
get
/competitors/{account_id}
Get Competitors Analytics
get
Retrieves analytics data for competitor accounts, including engagement metrics, follower counts, and post performance statistics.
Authorizations
Query parameters
account_idstringOptional
ID of the social media account to filter competitors analytics for
competitor_idstringOptional
Specific competitor account ID to analyze
querystringOptional
Search filter for competitor account names
fromstring · dateOptional
Start date for analytics data (ISO 8601 format, e.g., 2023-01-01)
tostring · dateOptional
End date for analytics data (ISO 8601 format, e.g., 2023-12-31)
pageintegerOptional
Page number for pagination (default: 0)
sort_bystring · enumOptional
Field to sort results by
Possible values:
sort_typestring · enumOptional
Sort direction
Possible values:
Header parameters
Publer-Workspace-IdstringRequired
ID of the workspace to retrieve competitors analytics from
Responses
200
Successful operation
application/json
totalintegerOptional
Total number of competitor accounts
401
Unauthorized
application/json
403
Permission denied - requires analytics access or paying subscription
application/json
422
Unprocessable entity - service error
application/json
get
/competitors/{account_id}/analytics
Get Hashtag Insights
get
Retrieves comprehensive analytics data for hashtags used in published posts. Provides metrics like reach, engagement, likes, comments, shares, and video views for each hashtag, along with recent posts using each hashtag and hashtag performance scores.
Authorizations
Path parameters
account_idstringOptional
Filter hashtags for a specific social media account ID. If omitted, includes all workspace accounts
Query parameters
fromstring · dateOptional
Start date for hashtag insights data range (YYYY-MM-DD format). Filters posts scheduled on or after this date
Example: {"value":"2024-01-01"}
tostring · dateOptional
End date for hashtag insights data range (YYYY-MM-DD format). Filters posts scheduled on or before this date
Example: {"value":"2024-12-31"}
sort_bystring · enumOptional
Field to sort hashtag results by. Supports various engagement and performance metrics
Possible values:
sort_typestring · enumOptional
Sort order direction
Possible values:
pageintegerOptional
Page number for pagination (0-based indexing). Each page contains 10 hashtags
querystringOptional
Search query to filter hashtags by name using case-insensitive matching
member_idstringOptional
Filter hashtags by specific workspace member ID
Header parameters
Publer-Workspace-IdstringRequired
ID of the workspace to retrieve insights from
Responses
200
Hashtag insights data with analytics metrics and pagination information
application/json
totalintegerOptional
Total number of hashtags matching the filter criteria (for pagination)
401
Unauthorized
application/json
403
Permission denied - requires analytics access or paying subscription
application/json
get
/analytics/{account_id}/hashtag_insights
Get Hashtag Performing Posts
get
Retrieves the top performing posts for a specific hashtag. Returns up to 6 posts that used the hashtag, with comprehensive analytics metrics including engagement, reach, likes, comments, shares, and video views.
Authorizations
Path parameters
account_idstringOptional
Filter posts for a specific social media account ID. If omitted, includes all workspace accounts
Query parameters
hashtagstringRequired
The hashtag to retrieve performing posts for (with # symbol). This parameter is required to filter posts by the specific hashtag
Example: {"value":"socialmedia"}
fromstring · dateOptional
Start date for posts data range (YYYY-MM-DD format). Filters posts scheduled on or after this date
Example: {"value":"2024-01-01"}
tostring · dateOptional
End date for posts data range (YYYY-MM-DD format). Filters posts scheduled on or before this date
Example: {"value":"2024-12-31"}
sort_bystring · enumOptional
Field to sort post results by. Supports various engagement and performance metrics
Possible values:
sort_typestring · enumOptional
Sort order direction
Possible values:
member_idstringOptional
Filter posts by specific workspace member ID
querystringOptional
Search query to filter posts by content text, title, or link information using case-insensitive matching
Header parameters
Publer-Workspace-IdstringRequired
ID of the workspace to retrieve posts from
Responses
200
Hashtag performing posts data with analytics metrics
application/json
Array of top performing posts using the specified hashtag (up to 6 posts)
idstringOptional
Unique identifier for the post
textstringOptional
Post content text
titlestringOptional
Post title if available
scheduled_atstring · date-timeOptional
Date and time when post was scheduled/published
account_idstringOptional
ID of the social media account that published this post
hashtagsstring[]Optional
Array of hashtags used in this post
401
Unauthorized
application/json
403
Permission denied - requires analytics access or paying subscription
application/json
get
/analytics/{account_id}/hashtag_performing_posts
Extract Link Metadata
post
Extracts metadata from a URL including title, description, images, and more. Useful for previewing links before creating a post.
Authorizations
AuthorizationstringRequired
API key authentication. Format: "Bearer-API YOUR_API_KEY"
Body
urlstringRequired
The URL to extract metadata from
Responses
200
Successful operation
application/json
401
Unauthorized
application/json
422
Unprocessable Entity - Invalid URL
application/json
post
/posts/links
Get Post Post Insights
get
Retrieves comprehensive analytics data for published posts with advanced filtering, sorting, and pagination capabilities.
Authorizations
Path parameters
account_idstringOptional
Filter posts for a specific social media account ID. If omitted, includes all workspace accounts. Used with competitors parameter for competitor-specific analysis
Query parameters
competitorsstring · enumOptional
Include competitor analysis data. Set to 'true' to retrieve competitor post insights
Possible values:
competitor_idstringOptional
Specific competitor account ID to analyze when competitors=true. Works in conjunction with account_id parameter
fromstring · dateRequired
Start date for post insights data range (YYYY-MM-DD format). Filters posts scheduled on or after this date
Example: {"value":"2024-01-01"}
tostring · dateRequired
End date for post insights data range (YYYY-MM-DD format). Filters posts scheduled on or before this date
Example: {"value":"2024-12-31"}
querystringOptional
Search query to filter posts by text content, title, link description, or video title using case-insensitive matching
postTypestring · enumOptional
Filter posts by specific post type (e.g., image, video, link, text, carousel)
Possible values:
sort_bystring · enumOptional
Field to sort results by. Supports various engagement and performance metrics
Possible values:
sort_typestring · enumOptional
Sort order direction
Possible values:
pageintegerOptional
Page number for pagination (0-based indexing). Each page contains 10 posts
member_idstringOptional
Filter posts by specific workspace member/user ID who created or manages the posts
Header parameters
Publer-Workspace-IdstringRequired
ID of the workspace to retrieve insights from
Responses
200
Post insights data with analytics metrics and pagination information
application/json
totalintegerOptional
Total number of posts matching the filter criteria (for pagination)
401
Unauthorized
application/json
403
Permission denied - requires analytics access or paying subscription
application/json
get
/analytics/{account_id}/post_insights
Update Post
put
Updates an existing post. The behavior differs depending on whether the post is already published or not.
Authorizations
AuthorizationstringRequired
API key authentication. Format: "Bearer-API YOUR_API_KEY"
Path parameters
idstringRequired
ID of the post to update
Header parameters
Publer-Workspace-IdstringRequired
ID of the workspace containing the post
Body
Responses
200
Post updated successfully
application/json
idstringOptional
Unique identifier for the post
Example: 68176f0e8bee9dc9b0ce3427
textstringOptional
Post text content
Example: Check out our new product launch!
statestringOptional
Current state of the post
Example: scheduled
typestringOptional
Type of post
Example: photo
account_idstringOptional
ID of the social account
Example: 63c675b54e299e9cf2b667ea
scheduled_atstringOptional
Scheduled publication time
Example: 2025-05-15T14:30:00.000+02:00
created_atstringOptional
Creation timestamp
Example: 2025-04-28T10:15:23.000+02:00
updated_atstringOptional
Last update timestamp
Example: 2025-04-29T11:30:45.000+02:00
post_linkstringOptional
Link to the published post on the social network
Example: https://facebook.com/post/123456789
autobooleanOptional
Whether this post was auto-scheduled
401
Unauthorized
application/json
403
Forbidden - You cannot update a post that has been published with approval
application/json
422
Unprocessable Entity - Error message explaining why the post couldn't be updated
application/json
put
/posts/{id}
Schedule posts
post
Schedule one or more posts for publishing. Supports immediate publishing, scheduled publishing, auto-scheduling, recurring posts, and more.
Authorizations
AuthorizationstringRequired
API key authentication. Format: "Bearer-API YOUR_API_KEY"
Header parameters
Publer-Workspace-IdstringRequired
ID of the workspace to schedule posts in
Body
Responses
200
Posts scheduled successfully
application/json
successbooleanOptional
Whether the job was created successfully
Example: true
400
Invalid scheduling parameters
application/json
401
Unauthorized
application/json
403
Permission denied or missing required scope
application/json
post
/posts/schedule
Create post
post
Creates a new social media post. Can be scheduled for immediate publishing, future publishing, or saved as a draft.
Authorizations
AuthorizationstringRequired
API key authentication. Format: "Bearer-API YOUR_API_KEY"
Header parameters
Publer-Workspace-IdstringRequired
ID of the workspace to create post in
Body
Responses
200
Post creation job initiated
application/json
successbooleanOptional
Whether the job was created successfully
Example: true
400
Invalid post data
application/json
401
Unauthorized
application/json
403
Permission denied or missing required scope
application/json
post
/posts/schedule/publish
Get job status
get
Check the status of an asynchronous job, including URL media uploads
Authorizations
AuthorizationstringRequired
API key authentication. Format: "Bearer-API YOUR_API_KEY"
Path parameters
job_idstringRequired
ID of the job to check
Header parameters
Publer-Workspace-IdstringRequired
ID of the workspace to retrieve posts from
Responses
200
Job status retrieved successfully
application/json
successbooleanOptional
Whether the request was successful
Example: true
401
Unauthorized
application/json
403
Permission denied or missing required scope
application/json
get
/job_status/{job_id}
Upload a media file directly
post
Upload a media file (image, video, or document) to be used in social media posts
Authorizations
AuthorizationstringRequired
API key authentication. Format: "Bearer-API YOUR_API_KEY"
Header parameters
Publer-Workspace-IdstringRequired
ID of the workspace to upload media
Body
filestringRequired
direct_uploadbooleanOptional
Whether to upload directly to our S3 cloud (slower, but required if you need the final media URL)