Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
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.
A Business Publer account
Basic familiarity with HTTP/JSON APIs
A command-line tool (curl) or API client (Postman, Insomnia)
Sign in to Publer and verify you have Business plan access.
Go to Settings → Access & Login → API Keys.
Click Create API Key.
Enter a descriptive name, then select scopes:
Before making other requests, let's retrieve your workspaces. The workspace ID is required in the header for most API operations:
Now you can use a workspace ID in your subsequent requests by including it in the header:
Next, let's retrieve the social media accounts in your workspace. You'll need the account IDs to specify where to publish your posts:
Make note of the account IDs as you'll need them to specify where to publish your content in the next step.
Make your first scheduled post with one API call:
The API returns a job ID that you can use to check the status of your request:
Posts are created asynchronously. Use the returned job_id to check progress:
If there's an error with your request, the response will include details about what went wrong:
List your scheduled posts to confirm creation:
Generate an API key
List workspaces → pick a workspace ID
List accounts → pick account IDs
Submit a post creation request
This async pattern scales across multiple workspaces, accounts, and post types.
Explore (photos, videos, links, polls)
Dive into and upload workflows
Learn about (drafts, recurring posts)
Review for platform-specific limits
For full API details, see the . For assistance, contact .
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.
Publer is an all-in-one social media management solution. From a single dashboard you can:
Schedule and publish posts
Manage accounts and team workspaces
Track performance with built-in analytics
Supported networks: Facebook, Instagram, Twitter/X, LinkedIn, Pinterest, YouTube, TikTok, Google Business Profile, WordPress, Telegram, Mastodon, Threads, Bluesky.
Create, schedule, and publish posts (text, images, videos, links, polls, carousels, PDFs)
Upload, organize, and reuse media assets (images, videos, GIFs, documents)
List workspaces, accounts, and user details
Retrieve posts and their performance analytics
Include your API token in every request header:
Manage and regenerate tokens in .
Generate an API key in your Publer Dashboard.
Validate your credentials:
Follow our to make your first API request
Explore the full for detailed endpoint docs.
If you need assistance with the API:
Review our for basic concepts
Check the for detailed endpoint information
Contact for technical issues
workspaces
accounts
posts
Click Create.
Copy and store the key securely—this value will not be shown again.
Poll job status until completed
Fetch posts to verify
Analytics:
Charts: Discover available analytics charts and fetch chart data for dashboards
Post Insights: Per‑post metrics with filtering, sorting, pagination, and competitor mode
Hashtag Analysis: Aggregate hashtag performance plus top performing posts per hashtag
Best Times to Post: Day/hour heatmap for optimal posting times (supports competitor view)
Members: Per‑member activity and performance (posts, reach, engagements)
Competitor Analysis: List competitors and compare followers, engagement, reach, and posting mix
Build custom integrations, dashboards, or bots
Base URL
https://app.publer.com/api/v1
Format
JSON
Auth Method
Bearer-API Token
Version
v1 (semantic versioning MAJOR.MINOR.PATCH)
Rate Limits
100 requests/2 minutes per user
curl -X GET "https://app.publer.com/api/v1/workspaces" \
-H "Authorization: Bearer-API YOUR_API_KEY"[
{
"id": "5f8d7a62c9e77e001f36e3a1",
"name": "My Primary Workspace",
"role": "owner",
"picture": "https://publer.io/uploads/workspaces/thumb_mini_workspace_123.png"
},
{
"id": "60a2e45f9b3c8d002a4b7c32",
"name": "Client Workspace",
"role": "admin",
"picture": "https://publer.io/uploads/workspaces/thumb_mini_workspace_456.png"
}
]Publer-Workspace-Id: 5f8d7a62c9e77e001f36e3a1curl -X GET "https://app.publer.com/api/v1/accounts" \
-H "Authorization: Bearer-API YOUR_API_KEY" \
-H "Publer-Workspace-ID: 5f8d7a62c9e77e001f36e3a1"{
"accounts": [
{
"id": "63c675b54e299e9cf2b667ea",
"name": "My Facebook Page",
"provider": "facebook",
"type": "page",
"picture": "https://publer.io/uploads/accounts/thumb_mini_facebook_page.jpg",
"status": "active"
},
{
"id": "63c675d74e299e9cf2b667eb",
"name": "Company LinkedIn Page",
"provider": "linkedin",
"type": "page",
"picture": "https://publer.io/uploads/accounts/thumb_mini_linkedin_page.jpg",
"status": "active"
},
{
"id": "63c675e94e299e9cf2b667ec",
"name": "Brand Twitter",
"provider": "twitter",
"type": "profile",
"picture": "https://publer.io/uploads/accounts/thumb_mini_twitter.jpg",
"status": "active"
}
]
}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
}
]
}
]
}
}'{
"job_id": "68176fa0f0eb419444bee686"
}curl -X GET "https://app.publer.com/api/v1/job_status/68176fa0f0eb419444bee686" \
-H "Authorization: Bearer-API YOUR_API_KEY" \
-H "Publer-Workspace-Id: 5f8d7a62c9e77e001f36e3a1"{
"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
}
}curl -X GET "https://app.publer.com/api/v1/posts?state=scheduled" \
-H "Authorization: Bearer-API YOUR_API_KEY" \
-H "Publer-Workspace-ID: 5f8d7a62c9e77e001f36e3a1"{
"posts": [
{
"id": "68176f0e8bee9dc9b0ce3427",
"text": "Status Update Post for 2025-05-07!",
"url": null,
"title": null,
"state": "scheduled",
"type": "status",
"account_id": "63c675b54e299e9cf2b667ea",
"user": {
"id": "5b1ec026db27977424e8599e",
"name": "Business User",
"picture": "https://publer.io/uploads/photos/thumb_mini_magick20250123-28707-otuw0w.png"
},
"scheduled_at": "2025-05-08T14:30:00.000+02:00",
"post_link": null
}
],
"total": 1
}Authorization: Bearer-API YOUR_API_TOKEN
Publer-Workspace-Id: YOUR_WORKSPACE_ID // Required on special cases
Content-Type: application/jsoncurl -H "Authorization: Bearer YOUR_API_TOKEN" \
https://app.publer.com/api/v1/meRetrieve profile and application settings for the currently authenticated user. Use this endpoint to adapt your integration to user preferences and entitlements.
Authentication: Bearer API token
Headers:
Authorization: Bearer-API YOUR_API_KEY
- Managing API keys and scopes
- Access workspace information
- Understanding API usage limits
Each social network offers unique post formats. Publer’s API supports these specialized types—click a format to dive into its implementation details:
Choose the Right Format Select the layout that matches your content goal and platform norms.
Follow Platform Guidelines Observe character limits, aspect ratios, and file-size rules.
Enhance Engagement Interactive formats (polls, carousels) tend to drive higher user interaction.
Test & Iterate Experiment across formats to discover what resonates best with your audience.
workspacesHeaders:
Authorization: Bearer-API YOUR_API_KEY
Retrieve all workspaces accessible by the authenticated user.
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.
Many endpoints require you to specify which workspace you’re operating in. Include the Publer-Workspace-Id header:
Users API - Access user profile information
Accounts API - Access social accounts within workspaces
Posts API — Create, schedule, and manage content
A RESTful JSON interface for automating social media workflows—scheduling, publishing, media management, and analytics—across multiple networks.
All endpoints share this root URL:
Include your API key and workspace ID on almost every request:
Use query parameters for filters and pagination:
Send JSON in the request body:
No request body is required (unless otherwise noted):
All responses are JSON.
Synchronous endpoints return the requested resource or collection.
Asynchronous endpoints (e.g., post creation) return a job_id:
Status codes indicate general error type (4xx, 5xx).
The response body contains an errors array:
200 OK
201 Created
202 Accepted (async)
400 Bad Request
Current version: v1 (in the URL path). We follow . Breaking changes only occur on MAJOR version bumps; you will be notified in advance.
Submit your request → 202 Accepted + {"job_id": "…"}
Poll the job status endpoint until complete:
All timestamps use ISO 8601 with timezone:
Example: 2025-05-04T14:58:35+00:00
Always use HTTPS.
Sensitive fields may be redacted.
Adhere to least-privilege scope selection.
For implementation examples, see the Quickstart Guide and sections on creating content, media handling, and network-specific formats.
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.
Media options help you:
Post your Facebook photos into albums.
Pin to specific Pinterest boards.
Protect your images and videos with custom watermarks.
Retrieve all available albums/boards and watermarks per account to use in your post scheduling workflows.
Use the following endpoint to list all available albums (for Facebook), boards (for Pinterest), and saved watermarks for the accounts in your workspace.
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.
Remove one or multiple posts—of any state—from your workspace. This endpoint enforces role-based permissions and state-specific restrictions.
Authentication: Bearer API token
Scope: posts
Headers:
Authorization: Bearer-API YOUR_API_KEY
Publer-Workspace-Id: YOUR_WORKSPACE_ID
Deletes one or more posts based on the provided IDs.
You may delete:
Posts you created
Posts in workspaces you own
Posts in workspaces where you have “post action” access
Pending-state deletions trigger a notification to the creator before removal.
- Retrieve and filter posts
- Modify existing posts
GET /api/v1/workspacescurl -X GET https://app.publer.com/api/v1/accounts \
-H "Authorization: Bearer-API YOUR_API_KEY" \
-H "Publer-Workspace-Id: 61a7c2e4f9e8c3b2d1e0f9a8"GET /api/v1/users/me403 Forbidden
404 Not Found
429 Too Many Requests
500 Internal Server Error
https://app.publer.com/api/v1/Authorization: Bearer-API YOUR_API_KEY
Publer-Workspace-Id: YOUR_WORKSPACE_ID
Content-Type: application/jsonGET /posts?state=scheduled&from=2025-04-20POST /posts
{
"bulk": {
"state": "scheduled",
"posts": [ … ]
}
}DELETE /posts/{post_id}{ "job_id": "6810dec617eae6d55d7a5e5b" }{ "errors": ["Detailed error message"] }GET /job_status/{job_id}{
"status": "completed",
"payload": { "failures": {} }
}YYYY-MM-DDThh:mm:ss±hh:mmalbums[].type
string
"facebook" or "pinterest"
watermarks
array
List of watermark objects
watermarks[].id
string
Watermark ID
watermarks[].name
string
Watermark name
watermarks[].opacity
number
Opacity percentage (0–100)
watermarks[].size
number
Relative size percentage (e.g., 15 = 15%)
watermarks[].position
string
Position on media (e.g., bottom_right)
watermarks[].default
boolean
Whether this is the default watermark
watermarks[].image
string
URL to the watermark image
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
Private drafts: only their creator can delete
Published posts requiring approval: restricted roles (e.g., editors) cannot delete
Queued posts (except reminders): cannot be deleted
Parameter
Type
Required
Description
post_ids
array
Yes
Array of post IDs to delete
accountsHeaders:
Authorization: Bearer-API YOUR_API_KEY
Publer-Workspace-Id: YOUR_WORKSPACE_ID
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.
Publer supports these network providers and account types:
Provider
Description
Supported Account Types
facebook
page, group, profile
instagram
business
twitter
Twitter/X
profile
linkedin
page, profile
Workspaces API - Manage organizational units
Posts API - Create and publish content to accounts
Media API - Upload media files for posting
Every Publer API request must include a valid API key. This guide shows you how to obtain, use, and manage your keys securely.
Sign in to your Publer account (Business plan).
Navigate to .
Click Create API Key.
Enter a descriptive name for your key.
Select only the scopes your integration needs (e.g., posts, media, accounts).
Click Create.
Copy and securely store the key — you won’t see it again.
Include your key in the Authorization header for every request. Also provide your workspace ID:
Example (list posts):
When creating an API key, you must select specific permission scopes based on your integration needs:
401 Unauthorized
• Missing or invalid Authorization header
• Key revoked or expired
403 Forbidden
• Insufficient scopes for the endpoint
• Missing Publer-Workspace-Id header
Always inspect the JSON error response for message and code.
Environment Variables
Store your key outside code—e.g., in a .env file:
Secrets Management Use a vault (AWS Secrets Manager, Azure Key Vault, HashiCorp Vault).
Key Rotation Rotate keys every 90–180 days, or after team changes/incidents.
If you continue to see authentication errors:
Confirm your key is active and not expired.
Verify you have the correct header names and values.
Double-check that your key has the required scopes.
Contact for assistance.
Automatically append a branded or informative signature to your social posts. Signatures help drive consistency and professionalism across your accounts.
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.
Before attaching a signature to your post, retrieve the available signatures for your account(s):
When scheduling or publishing a post, use the signature parameter within the relevant accounts object to append a signature to the post.
Example Request:
Account-specific: Up to 10 signatures per account.
Supported Networks: Most networks except Twitter/X and Bluesky (unless you have X Premium, due to character limits).
Photo Captions: On Facebook, configure whether the signature is included in photo captions for multi-photo posts.
Auto-Share: Signatures are not included when you auto-share a scheduled post.
Craft signatures that reinforce your brand identity.
Use signatures for legal disclaimers, campaign CTAs, or promotional blurbs.
Set a default signature for frequent use.
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.
GIF posts let you share looping animations with optional captions and metadata. Perfect for reactions, announcements, or adding personality to your feed.
Cross-Platform GIF Publishing
Custom Caption Support
Thumbnail Preview
Immediate or Scheduled Posting
Send to the scheduling endpoint (/posts/schedule) or immediate‐publish (/posts/schedule/publish):
Reference or upload your GIF via the .
Build your post object with "type": "gif".
(Optional) Add "thumbnail" and "name" for preview.
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.
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.
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.
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.
To schedule a Twitter/X long-form post, set the network type to "long_post" inside the details object for the "twitter" network:
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.
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.
Schedule posts for future publication across one or more social networks using the Publer API.
Include a valid ISO 8601 scheduled_at timestamp under each account:
Status: 200 OK
state
Must be set to "scheduled" for future publishing.
accounts[].scheduled_at
ISO 8601 timestamp (with Z or offset) specifying when to publish.
networks
Per-platform content configuration (e.g., facebook, twitter,
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.
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.
Verify: Poll /api/v1/job_status/{job_id}
- Details on different content formats
- Advanced AI-based scheduling options
- Setting up repeating content
- Platform-specific scheduling limitations
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.
Authentication: Bearer API token
Scope: posts
Headers:
Authorization: Bearer-API YOUR_API_KEY
Publer-Workspace-Id: YOUR_WORKSPACE_ID
Updates an existing post by ID. The behavior differs depending on whether the post is scheduled or already published.
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)
Threads
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.
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).
- Retrieve and filter posts
- Manage social media accounts
- Upload and manage media for posts
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.
Authentication: Bearer API token
Scope: analytics
Headers:
Authorization: Bearer-API YOUR_API_KEY
Publer-Workspace-Id: YOUR_WORKSPACE_ID
Retrieves analytics for each workspace member within a required date range. Optionally filter to a specific social account.
Fields:
engagements: Total engagements = likes + comments + shares + post clicks (platform-dependent).
posts: Number of posts created by the member in the range.
reach: Sum of post reach where supported by the platform/account type (may be omitted for unsupported types).
Date range is required; ensure from ≤ to.
If account_id is omitted, metrics aggregate across all accessible accounts in the workspace.
reach may be missing for networks that don’t expose member-level reach. Handle absent fields gracefully.
— Discover chart IDs and fetch chart data
— Per‑post performance analytics
— Hashtag performance
— Suggested posting time slots
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.
Authentication: Bearer API token
Scope: media
Headers:
Authorization: Bearer-API YOUR_API_KEY
Publer-Workspace-Id: YOUR_WORKSPACE_ID
Retrieve all social media accounts in a workspace.
Free trial users see placeholder data unless they supply specific query filters.
Paid accounts have full library access.
— Manage connected social accounts
— Create and schedule posts
— Upload new media files
Protect your creative content and reinforce your brand by automatically applying watermarks to photos and videos you share across your social accounts.
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.
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.
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.
DELETE /api/v1/postsGET /api/v1/accountsPOST /api/v1/posts/scheduleSafe Logging Never log full keys; mask all but the last 4 characters:
Always HTTPS Never send keys over plain HTTP.
Scope
Description
Example Endpoints
workspaces
Retrieve user's workspaces
/workspaces
accounts
Retrieve user's accounts of selected workspace
/accounts
posts
Manage user's posts
/posts
media
Upload and list media assets
/media
Mastodon
8 MB
Supports JPEG, PNG, WEBP, and GIF
Unlimited
—
networks.{provider}.media[].thumbnail
URL to a GIF thumbnail (e.g., WebP format)
networks.{provider}.media[].name
Descriptive name or title for the GIF
accounts[].id
Target social media account ID
accounts[].scheduled_at
ISO 8601 timestamp for scheduling (omit for immediate)
/posts/schedule or /posts/schedule/publish.Monitor /api/v1/job_status/{job_id} for completion.
4 MB
—
Twitter/X
15 MB
4×4 to 2048×2048 px resolution
Unlimited
Native GIF support
Telegram
50 MB
—
networks.{provider}.type
Must be "gif".
networks.{provider}.media
Array of exactly one media object
networks.{provider}.media[].id
"external" or your uploaded media ID
networks.{provider}.media[].type
Must be "gif".
networks.{provider}.media[].url
Direct URL to the GIF file
networks.{provider}.media[].path
Same as URL or CDN path
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)
linkedinAuthorization
Yes
Bearer-API YOUR_API_KEY
Publer-Workspace-Id
Yes
Workspace ID for scheduling posts
Content-Type
Yes
application/json
Accept
No
application/json (default)
console.log(`Using key ***${apiKey.slice(-4)}`);Authorization: Bearer-API YOUR_API_KEY
Publer-Workspace-Id: YOUR_WORKSPACE_ID
Content-Type: application/jsoncurl -X GET https://app.publer.com/api/v1/posts \
-H "Authorization: Bearer-API YOUR_API_KEY" \
-H "Publer-Workspace-Id: 5f8d7a62c9e77e001f36e3a1"PUBLER_API_KEY=your_api_key_herePOST /api/v1/posts/schedule
{
"bulk": {
"state": "scheduled",
"posts": [
{
"networks": {
"facebook": {
"type": "gif",
"text": "Check out this fun GIF!",
"media": [
{
"id": "external",
"type": "gif",
"url": "https://media.giphy.com/media/xyz/giphy.gif",
"path": "https://media.giphy.com/media/xyz/giphy.gif",
"thumbnail": "https://media.giphy.com/media/xyz/200w.webp",
"name": "Fun Reaction GIF"
}
]
}
},
"accounts": [
{
"id": "ACCOUNT_ID",
"scheduled_at": "2025-08-02T23:18:00+02:00"
}
]
}
]
}
}{
"bulk": {
"state": "scheduled",
"posts": [
{
"networks": {
"twitter": {
"type": "status",
"details": {
"type": "long_post"
},
"text": "This is a twitter long post"
}
},
"accounts": [
{
"id": "66e011b94e299eb49376c715",
"scheduled_at": "2025-09-24T14:16+02:00"
}
]
}
]
}
}{
"bulk": {
"state": "scheduled",
"posts": [
{
"networks": {
// network provider as key, e.g., facebook, twitter, etc
"facebook": {
"type": "status",
"text": "This post was scheduled through the Publer API! #ScheduledContent"
}
},
"accounts": [
{
"id": "66db83154e299efa19a2d8eb",
"scheduled_at": "2025-06-01T09:00:00Z"
}
]
}
]
}
}
curl -X POST https://app.publer.com/api/v1/posts/schedule \
-H "Authorization: Bearer-API YOUR_API_KEY" \
-H "Publer-Workspace-Id: YOUR_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"bulk": {
"state": "scheduled",
"posts": [{
"networks": {
"facebook": {
"type": "status",
"text": "This post was scheduled through the Publer API! #ScheduledContent"
}
},
"accounts": [{
"id": "66db83154e299efa19a2d8eb",
"scheduled_at": "2025-06-01T09:00:00Z"
}]
}]
}
}'{
"job_id": "6810dec617eae6d55d7a5e5b"
}networks.{provider}.text
string
Main post text (the signature is appended to this on publish)
Signature Management: Signatures must be created and managed for each social account individually.
accounts[].id
string
Target account ID
accounts[].scheduled_at
string
ISO 8601 timestamp for scheduling (omit for immediate publishing)
accounts[].signature
string
Signature ID to append (from the fetched signatures for this account)
networks.{provider}.type
string
Post type (e.g., "status", "photo", etc.)
• Text content
• Title
Parameter
Type
Required
Description
text
string
Yes
The main content text of the post
title
string
No
Title for the post (used in some networks)
Network
Updatable Fields
• Text content
YouTube
• Title (limited to 100 characters)
• Text/description (limited to 5000 characters)
Google Business
• Text content (called "summary" in Google's API, limited to 1500 characters)
• Text content (both description and message fields)
• Title (only for video posts, in the name field)
WordPress
• Title
• Content (HTML converted)
Telegram
• For status updates and links: Text content
Mastodon
account_ids[]: Accounts the member posted to.
user: Member info { id, name, picture }.
Insights refresh automatically (about every 24 hours). Use “Sync Insights” in the UI to update on demand.
from
date (YYYY-MM-DD)
Yes
Start date (inclusive).
to
date (YYYY-MM-DD)
Yes
End date (inclusive).
account_id
string
No
Restrict analytics to one social account. Omit for all workspace accounts.
used[]
boolean[]
Yes
Filter by usage status
source[]
string[]
No
Filter by source: canva, vista, postnitro, contentdrips, openai, favorites, upload
search
string
No
Full-text search on name or caption
ids[]
string[]
No
Specific media IDs (pagination and other filters ignored when set)
page
integer
No
Page number (0-based). Default: 0
types[]
string[]
Yes
Filter by media type: photo, video, gif
Use the Media Options endpoint 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.
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:
accounts[].id
string
Target account ID
accounts[].scheduled_at
string
ISO 8601 timestamp for scheduling (omit for immediate publish)
accounts[].watermark
object
Watermark object to apply (see below)
watermark.id
string
Watermark ID (from fetched media options)
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.
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.
Media Orientation: Watermarks are applied consistently regardless of image/video orientation.
Use Publer’s dedicated endpoints to search and select the correct location for your post:
Location Object Example:
When creating or scheduling a post, use the location object inside the relevant accounts array:
Example Request:
accounts[].id
string
Target account ID
accounts[].scheduled_at
string
ISO 8601 timestamp for scheduling (omit for immediate publish)
accounts[].location
object
Location object to tag (see below)
location.id
string
Unique identifier of the location (from search results)
Supported Networks: Location tagging is supported for Facebook Pages, Instagram Business and Threads accounts only.
Media Types Restrictions: You cannot add locations to Facebook regular videos, GIFs, Stories, or Reels scheduled via reminders.
Other Networks: Twitter/X no longer supports location tagging via API.
Search Required: Always search and select the correct location using the endpoints above before scheduling your post.
Always verify the location by name and address before tagging.
Tagging your business or event location can boost local discovery and engagement.
Use location tags for promotions, events, or posts relevant to specific regions
Authorization: Bearer-API YOUR_API_KEYPubler-Workspace-Id: YOUR_WORKSPACE_ID
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.
account_id
string
No
Social account to analyze. Omit for all workspace accounts.
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
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.
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.
Charts — Discover chart IDs and fetch chart data
Post Insights — Per‑post performance analytics
Hashtag Analysis — Hashtag performance
Members — Workspace member analytics
pinterest
business, profile
youtube
YouTube
channel
tiktok
TikTok
profile
google
Google Business
location
wordpress
WordPress
blog
telegram
Telegram
channel
mastodon
Mastodon
profile
threads
Threads
profile
bluesky
Bluesky
profile
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.
Publer supports three types of draft states, each with different visibility and account connection requirements:
draft - Connected to specific social accounts with optional scheduling
draft_public - Workspace-wide drafts visible to all workspace members (posts without social accounts)
draft_private - Private drafts visible only to you (posts without social accounts)
Use the same scheduling endpoint—with a draft state—to save work-in-progress content without publishing.
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
Uses specific network configurations (e.g., facebook, instagram)
draft_public)Drafts visible to all workspace members for collaboration and review.
Key Features:
No accounts array required
No scheduled_at field
Uses default network configuration
draft_private)Drafts visible only to the creator for personal use and planning.
Key Features:
No accounts array required
No scheduled_at field
Uses default network configuration
For draft state: Use specific network keys (facebook, instagram, twitter, etc.)
For draft_public and draft_private: Use default
Save Often: Create drafts early in your content creation process to avoid data loss
Use Public Drafts for Collaboration: Share draft_public posts with your team for feedback and approvals
Pre-schedule Account Drafts: Add scheduled_at to draft posts for seamless transition to scheduled state
Create and schedule interactive polls on LinkedIn, Mastodon, and Twitter to engage your audience and gather feedback.
Cross-Platform Polls: One payload to post polls on multiple networks
Flexible Duration: Support for platform-specific duration limits
Option Constraints: Enforce character limits and unique choices
Scheduling: Publish immediately or at a specified time
Tip: When sending a multi-network poll, adhere to Twitter’s 25-character option limit and common duration (e.g., 1, 3, 7 days).
Use the unified scheduling endpoint:
Options live in options array; question must be in text.
2–4 options, ≤25 characters each.
Cannot edit after publishing.
Uses separate question and text.
Options ≤30 characters.
Up to 14-day duration.
Question goes in text.
Options ≤50 characters.
Poll can be edited after posting.
Keep questions clear and concise.
Use unique, contrasting options.
Align durations with campaign timelines.
Turn multiple images or documents into a scrollable PDF carousel in a single LinkedIn post. Perfect for presentations, portfolios, and multi-page documents.
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.
Upload Media Use the to upload images or documents and collect their IDs.
Compose Post
Set type: "photo", add media IDs.
Use high-resolution images or properly formatted documents for clarity.
Craft a concise title that accurately represents the carousel content.
Organize slides in logical order to guide viewers.
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.
Authentication: Bearer API token
Scope: analytics
Headers:
Authorization: Bearer-API YOUR_API_KEY
Publer-Workspace-Id: YOUR_WORKSPACE_ID
Retrieve chart definitions.
Returns a list of charts grouped by category (growth, insights, demographics). Different platforms expose different charts.
Account type values:
ig_business, fb_page, twitter, linkedin, youtube, tiktok, google, pin_business, pin_personal, threads, wordpress_oauth, in_profile, in_page, mastodon
Fetch data for one or more charts by ID. Returns current and previous period blocks for comparison.
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.
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.
- Manage social media accounts
— Track hashtag performance
— Suggested posting time slots
— Member (team) analytics
Publish content to social networks instantly using the Publer API. This method skips scheduling and sends posts for immediate delivery.
Use the standard bulk structure. Omit scheduled_at under accounts:
state: must be "scheduled" for immediate publishing
networks: per-network content configuration (facebook, twitter, linkedin, etc.)
Status: 200 OK
Use the returned job_id to poll /api/v1/job_status/{job_id} until status: "completed".
Delivery Timing
Posts are sent as soon as Publer processes the request.
Network-side processing may introduce slight delays.
Job remains in working state until all targets confirm receipt.
- Details on different content formats
- Information about uploading and managing media
- Platform-specific capabilities and limitations
Simple yet powerful status updates without media attachments. Text posts are widely supported, versatile, and often drive high engagement.
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
Leverage network-specific features: hashtags, mentions, rich formatting
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.
Flexible Scheduling Instant publish, scheduled posts, or auto-optimized time slots.
Below is an example showing a text post scheduled for multiple platforms:
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.
Include Clear CTAs Encourage engagement with direct calls-to-action.
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.
Authentication: Bearer API token
Scope: analytics
Headers:
{
"bulk": {
"state": "scheduled",
"posts": [
{
"networks": {
"facebook": {
"type": "status",
"text": "Check out our latest news!"
}
},
"accounts": [
{
"id": "63c675b54e299e9cf2b667ea",
"scheduled_at": "2025-06-13T10:16:00+02:00",
"signature": "680fa73ebd7195d33da6630b"
}
]
}
]
}
}PUT /api/v1/posts/:idGET /api/v1/analytics/membersGET /api/v1/media[
{
"id": "63c675b54e299e9cf2b667ea",
"albums": [],
"watermarks": [
{
"id": "680fa7bebd7195d33da6630d",
"name": "Brand Logo",
"opacity": 80,
"size": 6,
"position": "bottom_right",
"default": true,
"image": "https://cdn.example.com/watermarks/logo.png"
}
]
}
]{
"bulk": {
"state": "scheduled",
"posts": [
{
"networks": {
"facebook": {
"type": "video",
"text": "Watermark posts",
"media": [
{
"id": "67da8532075cdb33821384c4",
"name": "Follow your dreams.mp4",
"path": "https://cdn.example.com/videos/67da8532075cdb33821384c4.mp4",
"type": "video"
}
],
"details": {
"type": "reel"
}
}
},
"accounts": [
{
"id": "63c675b54e299e9cf2b667ea",
"scheduled_at": "2025-08-02T10:16:00+02:00",
"watermark": {
"id": "680fa7bebd7195d33da6630d",
"name": "Brand Logo",
"opacity": 80,
"size": 6,
"position": "bottom_right",
"default": true,
"image": "https://cdn.example.com/watermarks/logo.png"
}
}
]
}
]
}
}{
"id": "308281375929281",
"name": "Tirana",
"info": "Tirana, Albania ⋅ 590 follow this",
"verified": true
}{
"bulk": {
"state": "scheduled",
"posts": [
{
"networks": {
"facebook": {
"type": "status",
"text": "Facebook location"
}
},
"accounts": [
{
"id": "63c675b54e299e9cf2b667ea",
"scheduled_at": "2025-06-14T10:21:00+02:00",
"location": {
"id": "308281375929281",
"name": "Tirana",
"info": "Tirana, Albania ⋅ 590 follow this",
"verified": null,
"address": "Tirana, Albania",
"checkins": "590"
}
}
]
}
]
}
}GET /api/v1/analytics/:account_id/best_timesPOST /api/v1/posts/schedule/publishwatermark.name
string
Watermark label
watermark.opacity
number
Opacity (0–100, higher = more opaque)
watermark.size
number
Relative size percentage (e.g., 6 = 6% of media size)
watermark.position
string
Position on media (bottom_right, top_left, etc.)
watermark.default
boolean
Whether this is the default watermark
watermark.image
string
URL to the watermark image (PNG recommended)
accounts[].id
string
Yes (when accounts present)
Social account ID
accounts[].scheduled_at
string
No
ISO 8601 timestamp (only for "draft" state)
Organize by Purpose: Use private drafts for personal planning and public drafts for team collaboration
Authorization
Yes
Bearer-API YOUR_API_KEY
Publer-Workspace-Id
Yes
Workspace ID for scheduling posts
Content-Type
Yes
application/json
Accept
No
application/json (default)
bulk.state
string
Yes
Draft type: "draft", "draft_public", or "draft_private"
posts[].networks
object
Yes
Network configurations for the post
posts[].accounts
array
Only for "draft" state
Array of account objects with IDs and optional scheduling
No
Mastodon
In text
2–4, ≤50 chars
Up to 7 days
Yes
networks.{provider}.duration
integer
Poll duration in days (platform max limits apply).
accounts[].id
string
Target social account ID.
accounts[].scheduled_at
string
ISO 8601 timestamp for scheduling (omit to publish immediately).
Twitter/X
In text
2–4, ≤25 chars
Up to 7 days
No
Options limit applies across all networks
Separate question
2–4, ≤30 chars
networks.{provider}.type
string
Must be "poll".
networks.{provider}.text
string
Caption or question (Twitter/Mastodon).
networks.linkedin.question
string
Poll question (LinkedIn only).
networks.{provider}.options
string[]
Array of 2–4 unique options.
Up to 14 days
networks.linkedin.title
string
Document title (required)
accounts[].id
string
LinkedIn profile or page account ID
accounts[].scheduled_at
string
ISO 8601 timestamp for scheduling (omit to publish immediately)
Under details, set "type": "document".
Provide a title.
Schedule or Publish
Add scheduled_at under accounts to schedule.
Omit scheduled_at to publish immediately.
networks.linkedin.type
string
Must be "photo"
networks.linkedin.text
string
Post caption (optional)
networks.linkedin.media[]
array
Up to 100 items; each with "id" from Media Upload
networks.linkedin.details.type
string
Must be "document" to enable PDF carousel
Max Items
100 photos/pages
Supported Formats
JPEG, PNG, PDF, DOCX, PPTX
Media Mix
No GIFs or videos—photos/documents only
Title Requirement
title field is mandatory
File Size
No explicit size limit for photos; follows Media API rules
Editing
Cannot change media type after scheduling
accounts: list of target account IDs (no scheduled_at timestamp)Platform Requirements
All network-specific content rules still apply (e.g., character limits, media formats).
Some networks may perform additional reviews before public display.
Ensure the connected accounts have immediate-posting permissions.
Authorization
Yes
Bearer-API YOUR_API_KEY
Publer-Workspace-Id
Yes
Workspace ID
Content-Type
Yes
application/json
Accept
No
application/json (default)
Issue
Solution
Rate limiting
Space out immediate publishing requests to avoid triggering platform limits
Authentication errors
Check that social accounts are properly connected and authorized
Content rejection
Review platform guidelines for content that might be flagged
Processing delays
For media posts, allow extra time for media processing
1,500
For business updates
500
For pin descriptions
Telegram
4,096
Per message
Mastodon
500+
Varies by server (usually 500 minimum)
Threads
500
Maximum length
Bluesky
300
Maximum length
A/B Test Variations Schedule multiple text variants to measure which resonates best.
Network
Character Limit
Notes
10,000
Full text supported with formatting
Twitter/X
280
25,000 for premium accounts
3,000
Supports formatting like bold, italic
2,200
For feed post captions
networks.{provider}.type
Must be set to "status"
networks.{provider}.text
Your post copy string
accounts[].id
Target social account ID
accounts[].scheduled_at
ISO 8601 timestamp (for scheduling)
Google Business
Authorization
Yes
Bearer-API YOUR_API_KEY
Publer-Workspace-Id
Yes
Workspace ID
Content-Type
Yes
application/json
Accept
No
application/json (default)
Set auto: true and define range to enable auto-scheduling:
auto
boolean
Set to true to enable auto-scheduling
range.start_date
string
Earliest ISO 8601 timestamp for posting (inclusive)
range.end_date
string
Latest ISO 8601 timestamp for posting (inclusive, optional)
share_next
boolean
(Optional) When true, schedule in the very next available slot
Omit end_date and set share_next to schedule at the next open slot:
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.
Schedule: Creates the post at the selected time.
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.
Hands-Off Workflow: Let Publer handle timing so you focus on content.
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.
Monitor Jobs: Poll /api/v1/job_status/{job_id} to confirm success.
No available slots
Add or open time slots in your posting schedule within the date range.
Suboptimal timing
Expand the date range or refine your posting schedule.
Data insufficient
Post more content manually to build up engagement metrics.
POST /api/v1/posts/schedule{
"bulk": {
"state": "draft",
"posts": [
{
"networks": {
"facebook": {
"type": "status",
"text": "First Draft"
}
},
"accounts": [
{
"id": "647a0edddb2797b89044e2c1",
"scheduled_at": "2025-06-23T10:43:00+02:00"
}
]
}
]
}
}{
"bulk": {
"state": "draft_public",
"posts": [
{
"networks": {
"default": {
"type": "status",
"text": "Draft"
}
}
}
]
}
}{
"bulk": {
"state": "draft_private",
"posts": [
{
"networks": {
"default": {
"type": "status",
"text": "Private Draft"
}
}
}
]
}
}POST /api/v1/posts/schedule
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
{
"bulk": {
"state": "scheduled",
"posts": [{
"networks": {
"twitter": {
"type": "poll",
"text": "What’s your favorite season?",
"options": ["Spring", "Summer", "Autumn", "Winter"],
"duration": 7
},
"linkedin": {
"type": "poll",
"question": "What’s your favorite season?",
"text": "Vote now!",
"options": ["Spring", "Summer", "Autumn", "Winter"],
"duration": 7
},
"mastodon": {
"type": "poll",
"text": "What’s your favorite season?",
"options": ["Spring", "Summer", "Autumn", "Winter"],
"duration": 7
}
},
"accounts": [
{ "id": "TW_ACCOUNT_ID", "scheduled_at": "2025-06-10T09:00:00Z" },
{ "id": "LI_ACCOUNT_ID", "scheduled_at": "2025-06-10T09:00:00Z" },
{ "id": "MA_ACCOUNT_ID", "scheduled_at": "2025-06-10T09:00:00Z" }
]
}]
}
}{
"bulk": {
"state": "scheduled",
"posts": [
{
"networks": {
"linkedin": {
"type": "photo",
"text": "Description",
"media": [
{
"id": "680fa5cc48487c4ccbf8c146",
"name": "",
"caption": "Photo by KaLisa Veer on Unsplash:\n\nhttps://unsplash.com/photos/the-chrysler-building-is-framed-by-other-buildings-sdU2K71G8TI",
"path": "https://publer-dev.s3.amazonaws.com/uploads/photos/680fa5cc48487c4ccbf8c146.jpg",
"type": "photo",
"thumbnail": "https://publer-dev.s3.amazonaws.com/uploads/photos/thumb_680fa5cc48487c4ccbf8c146.jpg"
},
{
"id": "66f54e664e299e991eaafaeb",
"name": "pexels-christian-heitz-285904-842711.jpg",
"caption": null,
"path": "https://publer-dev.s3.amazonaws.com/uploads/photos/66f54e664e299e991eaafaeb.jpg",
"type": "photo",
"thumbnail": "https://publer-dev.s3.amazonaws.com/uploads/photos/thumb_66f54e664e299e991eaafaeb.jpg"
},
{
"id": "66f122324e299eb6bcc9af55",
"name": "",
"caption": "Photo by David Villasana on Unsplash:\n\nhttps://unsplash.com/photos/a-black-car-parked-in-front-of-a-white-building-Pf9KhOIylaM",
"path": "https://publer-dev.s3.amazonaws.com/uploads/photos/66f122324e299eb6bcc9af55.jpg",
"type": "photo",
"thumbnail": "https://publer-dev.s3.amazonaws.com/uploads/photos/thumb_66f122324e299eb6bcc9af55.jpg"
},
{
"id": "66df7c954e299e47dae172ac",
"name": "Cabin life",
"caption": "Photo by Karsten Winegeart on Unsplash:\n\nhttps://unsplash.com/photos/a-house-sitting-on-top-of-a-lush-green-hillside-xUyOWyCjJ_I",
"path": "https://publer-dev.s3.amazonaws.com/uploads/photos/66df7c954e299e47dae172ac.jpg",
"type": "photo",
"thumbnail": "https://publer-dev.s3.amazonaws.com/uploads/photos/thumb_66df7c954e299e47dae172ac.jpg"
},
{
"id": "66df7c8d4e299e47dae172ab",
"name": "",
"caption": "Photo by Edgar.infocus on Unsplash:\n\nhttps://unsplash.com/photos/a-car-driving-on-a-foggy-road-AwRcfU8T4dg",
"path": "https://publer-dev.s3.amazonaws.com/uploads/photos/66df7c8d4e299e47dae172ab.jpg",
"type": "photo",
"thumbnail": "https://publer-dev.s3.amazonaws.com/uploads/photos/thumb_66df7c8d4e299e47dae172ab.jpg"
},
{
"id": "66d04c6d4e299e51d9e1f747",
"name": "5574042b224543ecaf6989f6725dd555.jpeg",
"caption": null,
"path": "https://publer-dev.s3.amazonaws.com/uploads/photos/66d04c6d4e299e51d9e1f747.jpeg",
"type": "photo",
"thumbnail": "https://publer-dev.s3.amazonaws.com/uploads/photos/thumb_66d04c6d4e299e51d9e1f747.jpeg"
}
],
"details": {
"type": "document"
},
"title": "Title of the document"
}
},
"accounts": [
{
"id": "64c90c0d4e299e38dc86a284",
"scheduled_at": "2025-06-21T14:16+02:00"
}
]
}
]
}
}{
"bulk": {
"state": "scheduled",
"posts": [
{
"networks": {
// network provider as key, e.g., facebook, twitter etc.
"[network_provider]": {
"type": "[content_type]",
"text": "Post content",
// Additional properties based on content type
}
},
"accounts": [
{
"id": "account_id"
// No scheduled_at parameter
}
]
}
]
}
}curl -X POST https://app.publer.com/api/v1/posts/schedule/publish \
-H "Authorization: Bearer-API YOUR_API_KEY" \
-H "Publer-Workspace-Id: YOUR_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"bulk": {
"state": "scheduled",
"posts": [
{
"networks": {
"facebook": {
"type": "status",
"text": "Just published this update via the Publer API! #RealTimePosting"
}
},
"accounts": [
{ "id": "66db83154e299efa19a2d8eb" }
]
}
]
}
}'{
"job_id": "6810dec617eae6d55d7a5e5b"
}{
"bulk": {
"state": "scheduled",
"posts": [
{
"networks": {
"facebook": {
"type": "status",
"text": "Exciting news! We're launching our new product line next week. #NewLaunch #ProductAnnouncement"
},
"twitter": {
"type": "status",
"text": "Big announcement coming next week! Our new product line is almost here 🚀 #NewLaunch #ProductAnnouncement"
},
"linkedin": {
"type": "status",
"text": "We're thrilled to announce our new product line launching next week. Stay tuned for more details! #NewLaunch #ProductAnnouncement"
}
},
"accounts": [
{
"id": "account_id_for_facebook",
"scheduled_at": "2025-05-20T14:30:00Z" // Optional, depending on publishing method
},
{
"id": "account_id_for_twitter",
"scheduled_at": "2025-05-20T15:00:00Z" // Optional, depending on publishing method
},
{
"id": "account_id_for_linkedin",
"scheduled_at": "2025-05-20T16:00:00Z" // Optional, depending on publishing method
}
]
}
]
}
}POST /api/v1/posts/schedule{
"bulk": {
"state": "scheduled",
"posts": [
{
"networks": {
"facebook": {
"type": "status",
"text": "Let Publer pick the best time for this post!"
}
},
"accounts": [
{ "id": "ACCOUNT_ID" }
],
"range": {
"start_date": "2025-05-23T07:45:00Z",
"end_date": "2025-05-31T23:59:00Z"
},
"auto": true
}
]
}
}{
"bulk": {
"state": "scheduled",
"posts": [{
"networks": {
"facebook": {
"type": "status",
"text": "Let Publer choose the best time!"
}
},
"accounts": [{ "id": "66f509f7db2797026a37ba76" }],
"range": {
"start_date": "2025-05-23T07:45:00Z",
"end_date": "2025-05-31T23:59:00Z"
},
"auto": true
}]
}
}{
"bulk": {
"state": "scheduled",
"posts": [{
"networks": {
"facebook": {
"type": "status",
"text": "Post in next available slot"
}
},
"accounts": [{ "id": "66f509f7db2797026a37ba76" }],
"range": { "start_date": "2025-05-23T07:45:00Z" },
"share_next": true,
"auto": true
}]
}
}blueskyshow_percentage
Indicates client should render as percentage.
from ≤ to when providing dates.Not all charts are available for every account_type.
Apply client‑side caching for chart definitions to reduce requests.
account_type
string
No
Filter charts for a specific account type.
id
Unique chart identifier (use in chart_ids[]).
title
Display title.
group_id
Chart group: growth, insights, demographics.
tooltip
Short explanatory text.
type
Suggested visualization: vertical, horizontal, side_by_side.
last_value
Show latest value highlight.
account_id
string
No
When provided, returns data for that account only; when omitted, returns aggregate across the workspace (where supported).
chart_ids[]
string[]
Yes
One or more chart IDs from /api/v1/analytics/charts. Example: chart_ids[]=followers&chart_ids[]=post_engagement
from
string (YYYY-MM-DD)
Yes if to used
Start date (inclusive). Defaults to workspace range if omitted with to.
to
string (YYYY-MM-DD)
Yes if from used
current
Object keyed by chart ID with current period series.
previous
Matching structure for the previous (comparison) period.
data[]
Array of { date, value } points.
last_value
Latest cumulative snapshot (growth charts).
total
Period aggregate sum (engagement / sum charts).
End date (inclusive). Defaults to workspace range if omitted with from.
Authorization
Yes
Bearer-API YOUR_API_KEY
Publer-Workspace-Id
Yes
Your workspace identifier
Content-Type
Yes
application/json
Accept
No
application/json (default)
Include a recurring object under each post:
state: must be "recurring" for recurring posts
start_date
string
ISO 8601 timestamp for the first occurrence
end_date
string
ISO 8601 timestamp to stop recurrence (optional)
repeat
string
The interval unit for repetition. Supported values: "daily", "weekly", "monthly", yearly
Every other Tuesday and Thursday:
To create a recurring post, specify the recurrence parameters inside the recurring object:
start_date: The date and time for the first occurrence.
end_date: The last date and time for recurring posts to be generated.
repeat: The repeat interval unit: "daily", "weekly", "monthly" or "yearly".
repeat_rate: Frequency of the interval. For example, 1 with "weekly" means every week, 2 means every other week, etc.
days_of_week: Which days of the week to post on (e.g., [1, 3] for Tuesday and Thursday).
Platform
Recurring Support
Notes
Full support
No special requirements
Full support
No special requirements
Full support
No special requirements
Limited
Requires 10+ variations using Spintax Generator
Regular reminders (e.g., weekly tips).
Monthly newsletters or reports.
Annual event notifications (e.g., holidays).
Routine promotions or offers.
Evergreen Content: Use for timeless messages that benefit from repetition.
Stop Conditions: Always set end_date to avoid indefinite runs.
Combine Actions: Add follow-up comments or auto-deletion for full lifecycle management.
Audience Consideration: Avoid fatigue by spacing posts appropriately.
Recurring Posts: Fixed dates/times on a repeating schedule.
Recycling Posts: Fills open slots based on your posting calendar.
Authorization
Yes
Bearer-API YOUR_API_KEY
Publer-Workspace-Id
Yes
Your workspace identifier
Content-Type
Yes
application/json
Accept
No
application/json (default)
Include a recycling object in your payload:
solo
boolean
true to recycle this post individually (not grouped)
gap
number
Interval between reposts (e.g., 2 for every 2 units)
gap_freq
string
Unit of interval: Day, Week, or Month
start_date
string
ISO date when recycling begins (e.g., YYYY-MM-DD)
Recycle every 2 weeks, up to 3 times:
Recycle monthly until end of year:
Create a post with recycling settings.
Publer queues the post for reuse.
After each gap interval, the post is republished.
Recycling stops when expire_count or expire_date is reached.
Due to API limitations and anti-spam policies, recycling has some platform-specific constraints:
Platform
Recycling Support
Notes
Full support
No special requirements
Full support
No special requirements
Full support
No special requirements
Limited
Requires 10+ variations using Spintax Generator
Promote evergreen blog posts or resources.
Remind followers of ongoing events or offers.
Keep your feed active with minimal manual effort.
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).
Monitor engagement metrics to adjust recycling strategy.
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).
Single API call to schedule or publish…
Supports up to 5 photos or 1 video per Pin
Clickable external URL
Specify the target board with album_id
Optional alt text for accessibility
Max Media
1 video or up to 5 photos
Supported Formats
JPEG, PNG, GIF, MP4
Link URL
External links only (use url field)
Alt Text
Optional (media[].alt_text)
Board Selection
Use accounts[].album_id to pick a Pinterest board
networks.pinterest.type
string
Must be "photo".
networks.pinterest.text
string
Caption or description for the Pin.
networks.pinterest.media
array
List of media objects (1 video or up to 5 photos).
networks.pinterest.media[].id
string
"external-X" or media ID from Publer.
Select Account & Board
Add your Pinterest account.id and target album_id.
Upload/Reference Media
Upload up to 5 photos or 1 video to Publer, then reference each with its id.
Compose Pin
Set type: "photo".
Provide text, title, and url.
Optionally add alt_text.
Schedule or Publish
To schedule, include scheduled_at.
To publish now, call /posts/schedule/publish or omit scheduled_at.
Use high-resolution images or video for best display.
Keep the title and text concise to encourage clicks.
Ensure the URL is valid and leads to valuable content.
Organize Pins into relevant Boards for better discoverability.
Add alt text for accessibility and SEO benefits.
Authorization: Bearer-API YOUR_API_KEYPubler-Workspace-Id: YOUR_WORKSPACE_ID
Retrieve competitor accounts for the workspace or scoped to a specific social account.
Omit :account_id to list all competitors across the workspace.
Provide :account_id to list competitors tied to a single social account.
account_id
string
No
Social account ID to scope competitors.
Fields:
provider: Social network (e.g., instagram, facebook, twitter).
name: Display name of the competitor account.
social_id: Network-unique ID.
picture: Profile avatar URL.
type: Account type (user, page, business, etc.).
competitor_sync_in_queue: Whether a sync job is queued.
username: Handle (available for twitter, instagram, facebook).
verified: Whether the account is verified (available for twitter, facebook).
Fetch paginated analytics for competitor accounts with filtering, sorting, and date range selection.
Use account_id to focus on competitors relevant to a specific social account.
Filter by competitor_id or search by name with query.
Sort by followers, reach, engagement, and post mix counts.
account_id
string
No
Scope analytics to one social account (path variant).
account_id
string
No
Scope analytics to one social account (query variant).
competitor_id
string
No
Analyze a specific competitor.
query
string
No
Fields:
insights[]: One item per competitor.
account: Basic account info and sync status; my_account indicates if it’s your own account.
followers: Current follower count.
followers_growth: Net growth in the selected period.
engagement: Total interactions (definition varies by network).
engagement_rate: Percentage (available for Twitter).
reach: Total reach (not available for Instagram/Facebook).
posts_count, videos_count, photos_count, links_count, statuses_count: Posting mix counts.
total: Total competitors matching filters (use with page to paginate).
Reach availability: reach is not returned for Instagram/Facebook competitor analytics.
Best times for competitors: Use Best Times endpoint with competitor mode to view competitors’ optimal posting hours:
GET /api/v1/analytics/:account_id/best_times?competitors=true&competitor_id=...
Competitor post insights: Use the endpoint in competitor mode:
GET /api/v1/analytics/:account_id/post_insights?competitors=true&competitor_id=...
Post Insights — Per‑post performance analytics (supports competitor mode)
Best Times — Suggested posting times (supports competitor mode)
Hashtag Analysis — Hashtag performance
Charts — Discover chart IDs and fetch chart data
type
string
Must be "carousel".
text
string
Caption shown above the carousel cards.
sublinks[]
array
List of carousel items (max 10).
url
string
Target link for this card.
provider_display
string
(Optional) Display domain or provider name.
title
string
Card title (overrides fetched metadata).
description
string
Card description (overrides fetched metadata).
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).
Syncing: Published carousel posts can only sync back as regular link posts (no carousel structure).
Select Page
Choose a Facebook Page account in the accounts array.
Define Sublinks
Provide url, title, description, and images for each card.
Arrange Order Order sublinks as they should appear (array index defines order).
Schedule or Publish
For scheduled: set scheduled_at under accounts.
For immediate: omit scheduled_at and use /posts/schedule/publish.
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.
A/B Test CTAs
Experiment with LEARN_MORE, SIGN_UP, and other button types.
Advanced Customization Captions and location tags where available.
Resolution Optimization Automatic resizing and format handling per network.
Unlimited
No restriction
Yes
No restrictions on photo size.
10
8 MB
Yes
Minimum resolution: 320x320 px, automatically cropped.
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.
Below is an example showing a photo post scheduled for multiple platforms.
Omit scheduled_at for immediate posts.
networks.{provider}.type
Must be "photo".
networks.{provider}.media
Array of { id, type, caption } objects.
accounts[].id
Target social account ID.
accounts[].scheduled_at*
ISO 8601 timestamp for scheduling (optional).
* Omit scheduled_at when publishing immediately.
Upload Images: Use the Media Handling API to upload files.
Receive IDs: Note each media object’s id.
Compose Post: Reference those IDs in your media array.
Publish/Schedule: Send the payload to the posts endpoint.
Optimize Quality: Compress and resize images to platform specs.
Descriptive Alt Text: Enhance accessibility and SEO.
Tailor Captions: Adjust tone and length per network.
Experiment Carousels: Test image order to boost engagement.
Consistent Branding: Use uniform styles and watermarks.
Authorization: Bearer-API YOUR_API_KEYPubler-Workspace-Id: YOUR_WORKSPACE_ID
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.
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 and optionally narrow to a single competitor via competitor_id , see Competitor Analysis how to fetch competitor ids.
account_id
string
No
Social account ID to scope results. When used with competitors: true, it will filter all competitor posts related to this account.
competitors
string
No
For competitor insights. true or false (default false).
competitor_id
string
No
Competitor account ID to analyze (requires competitors=true).
from
date (YYYY-MM-DD)
Yes
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).
Engagement Rate (%) ≈ engagement / reach * 100
Click‑Through Rate (%) ≈ link_clicks / reach * 100
Reach Rate (%) ≈ reach / followers * 100 (where available)
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).
Charts — Discover chart IDs and fetch chart data
Hashtag Analysis — Track hashtag performance
Best Times — Suggested posting time slots
Members — Member (team) analytics
location.name
string
Name of the location
location.info
string
Additional info about the location (optional)
location.verified
boolean
Whether the location is verified (optional)
location.address
string
Physical address (optional)
location.checkins
integer
Number of check-ins (optional)
Start date (inclusive).
to
date (YYYY-MM-DD)
Yes
End date (inclusive).
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.
Authentication: Bearer API token
Scope: posts
Headers:
Authorization: Bearer-API YOUR_API_KEY
Publer-Workspace-Id: YOUR_WORKSPACE_ID
Retrieve posts with optional filters and pagination.
State Values
Type Values
Photo posts scheduled next month containing “launch”
GET /posts?state=scheduled&postType=photo&from=2025-06-01&to=2025-06-30&query=launch
All failed posts across accounts
GET /posts?state=failed&account_ids[]=63c675b54e299e9cf2b667ea&account_ids[]=64d786c54e299e9cf2b667fb
Drafts by a workspace member
GET /posts?state=draft&member_id=5b1ec026db27977424e8599e
- List social media accounts
- Upload and manage media for posts
- Post creation endpoints
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.
2-minute fixed
100 requests
Note: If you need higher throughput for your integration, see below.
When you reach the rate limits, every API response includes these headers so you can monitor your rate limit status:
Example Response Headers
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.
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.
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
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
For integrations requiring a higher rate limit, please contact us with:
Your expected request volume (per minute/hour/day)
Use case description and critical endpoints
Project or company name and contact info
Email:
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.
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.
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.
Choose between Schedule, Auto Schedule, or Recycle modes.
Send a POST request to the scheduling endpoint with your bulk payload:
Example Payload:
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.
Recycle:
Set bulk.state
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.
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.
Share URLs with rich previews (title, description, image, and call-to-action) across your social networks via the Publer API.
Link posts display a URL preview alongside optional caption text. You control metadata (title, description, images, CTA) to enhance engagement.
Rich previews with title, description, and image
Custom call-to-action buttons (e.g., LEARN_MORE, SIGN_UP)
Platform-specific metadata overrides
Schedule or publish immediately
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.
Use the unified scheduling endpoint (/posts/schedule) or the immediate-publish endpoint (/posts/schedule/publish):
Note: You can also include
original_title,original_description, andoriginal_imagesif you pre‐fetch metadata yourself, but only thelink.*fields above are required.
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 object.
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.
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.
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.
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.
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
GET /api/v1/analytics/chartsGET /api/v1/analytics/:account_id/chart_dataPOST /api/v1/posts/schedule{
"bulk": {
"state": "recurring",
"posts": [
{
"networks": {
"default": {
"type": "status",
"text": "Weekly reminder: Check our latest updates every Monday!"
}
},
"accounts": [
{ "id": "ACCOUNT_ID" }
],
"recurring": {
"start_date": "2025-06-05T13:29+02:00",
"end_date": "2025-07-21T13:29+02:00",
"repeat": "weekly",
"days_of_week": [
1,
4,
6
],
"repeat_rate": 1
}
}
]
}
}{
"bulk": {
"state": "recurring",
"posts": [{
"networks": {
"facebook": {
"type": "status",
"text": "Weekly reminder: Check our latest updates every Monday!"
}
},
"accounts": [{
"id": "66f509f7db2797026a37ba76"
}],
"recurring": {
"start_date": "2025-06-05T13:29+02:00",
"end_date": "2025-07-21T13:29+02:00",
"repeat": "weekly",
"days_of_week": [
1
],
"repeat_rate": 1
}
}]
}
}{
"bulk": {
"state": "recurring",
"posts": [{
"networks": {
"facebook": {
"type": "status",
"text": "Biweekly product update: See what's improved!"
}
},
"accounts": [{
"id": "66f509f7db2797026a37ba76"
}],
"recurring": {
"start_date": "2025-06-05T13:29+02:00",
"end_date": "2025-07-21T13:29+02:00",
"repeat": "weekly",
"days_of_week": [
1,
3,
],
"repeat_rate": 1
}
}]
}
}POST /api/v1/posts/schedule{
"bulk": {
"state": "scheduled",
"posts": [
{
"networks": {
"facebook": {
"type": "status",
"text": "This content will be recycled multiple times."
}
},
"accounts": [
{ "id": "66f509f7db2797026a37ba76" }
],
"recycling": {
"solo": true,
"gap": 2,
"gap_freq": "Week",
"start_date": "2025-06-01",
"expire_count": 3
}
}
]
}
}{
"bulk": {
"state": "scheduled",
"posts": [{
"networks": {
"facebook": { "type": "status", "text": "Evergreen reminder!" }
},
"accounts": [{ "id": "66f509f7db2797026a37ba76" }],
"recycling": {
"gap": 2,
"gap_freq": "Week",
"expire_count": 3
}
}]
}
}{
"bulk": {
"state": "scheduled",
"posts": [{
"networks": {
"default": { "type": "status", "text": "Monthly promotion reminder!" }
},
"accounts": [{ "id": "66f509f7db2797026a37ba76" }],
"recycling": {
"gap": 1,
"gap_freq": "Month",
"start_date": "2025-06-01",
"expire_date": "2025-12-31"
}
}]
}
}{
"bulk": {
"state": "scheduled",
"posts": [
{
"networks": {
"pinterest": {
"type": "photo",
"text": "Check out our new blog post!",
"media": [
{
"id": "external-0",
"type": "photo",
"path": "https://cdn.example.com/images/post1.jpg",
"thumbnail": "https://cdn.example.com/images/post1-thumb.jpg",
"alt_text": "Screenshot of our blog homepage"
}
],
"title": "Our Latest Blog Article",
"url": "https://publer.com/blog"
}
},
"accounts": [
{
"id": "YOUR_PINTEREST_ACCOUNT_ID",
"scheduled_at": "2025-07-05T14:16:00+02:00",
"album_id": "934145216398624390"
}
]
}
]
}
}GET /api/v1/competitors/:account_idGET /api/v1/competitors/:account_id/analytics{
"bulk": {
"state": "scheduled",
"posts": [
{
"networks": {
"facebook": {
"type": "carousel",
"text": "Explore our top features!",
"sublinks": [
{
"url": "https://publer.com",
"title": "Publer Dashboard",
"description": "Manage all your social accounts in one place.",
"images": [
"https://cdn.publer.com/images/dashboard1.jpg",
"https://cdn.publer.com/images/dashboard2.jpg"
],
"default_image": 0,
"call_to_action": "LEARN_MORE"
},
{
"url": "https://publer.com/pricing",
"title": "Pricing Plans",
"description": "Find the right plan for your team.",
"images": [
"https://cdn.publer.com/images/pricing.jpg"
],
"default_image": 0,
"call_to_action": "SIGN_UP"
}
]
}
},
"accounts": [
{
"id": "63c675b54e299e9cf2b667ea",
"scheduled_at": "2025-07-06T23:18:00Z"
}
]
}
]
}
}{
"bulk": {
"state": "scheduled",
"posts": [
{
"networks": {
"facebook": {
"type": "photo",
"text": "Our new office is complete! #OfficeLife",
"media": [
{
"id": "asset123456",
"type": "photo",
"caption": "Modern office with open layout"
},
{
"id": "asset123457",
"type": "photo",
"caption": "Collaborative meeting area"
}
]
},
"instagram": {
"type": "photo",
"text": "We’ve moved into our new HQ! 🏢✨",
"media": [
{ "id": "asset123456", "type": "photo", "caption": "Modern office space" },
{ "id": "asset123457", "type": "photo", "caption": "Meeting area" }
]
}
},
"accounts": [
{ "id": "FB_ACCOUNT_ID", "scheduled_at": "2025-05-20T14:30:00Z" },
{ "id": "IG_ACCOUNT_ID", "scheduled_at": "2025-05-20T15:00:00Z" }
]
}
]
}
}GET /api/v1/analytics/:account_id/post_insightsexpire_count
number
Maximum number of reposts
expire_date
string
ISO date to stop recycling (alternative to expire_count)
Limited
Requires 10+ variations using Spintax Generator
Google Business Profile
Limited
Requires 10+ variations using Spintax Generator
YouTube
Not supported
API limitations
TikTok
Not supported
API limitations
WordPress
Not supported
API limitations
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).
images
string[]
Array of image URLs for this card.
default_image
integer
Index (0-based) of the default image in images.
call_to_action
string
CTA button type: NO_BUTTON, LEARN_MORE, SIGN_UP, etc.
phone_number
string
(Optional) Phone number for call-to-action cards.
customized
boolean
(Optional) true if overriding the link’s default thumbnail or metadata.
TikTok
35
No restriction
Yes
Cannot mix photos with GIFs or videos.
Threads
20
8 MB
Yes
Cannot mix photos with GIFs or videos.
4
5 MB
Yes
Supports only up to 4 photos per post.
20
No restriction
Yes
Photos and GIFs are supported, cannot mix with videos.
Telegram
10
10 MB
Yes
Cannot mix photos with GIFs or videos.
Mastodon
4
8 MB
Yes
Supports JPEG, PNG, or WEBP formats.
Instagram Stories
15
20
25
Threads App Posts
150
200
250
TikTok Videos
15
20
25
Twitter / X Posts
25
50
100
Mastodon Posts
25
50
100
Bluesky Posts
25
50
100
LinkedIn Profile Posts
10
12
14
LinkedIn Page Posts
12
18
24
Pinterest Pins
12
24
36
Google Business Updates
5
10
15
YouTube Videos & Shorts
5
10
15
WordPress Articles
12
18
24
Telegram Messages
5
10
15
Implement exponential backoff when you approach or hit the limit.
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)
Facebook Posts & Reels
12 / day / profile
24 / day / profile
36 / day / profile
Facebook Stories
12
24
36
Instagram Posts & Reels
15
20
25
Individually customize each post (content, media, timing, etc.).
Posts without a scheduled_at field use the account’s posting schedule.
posts[].accounts
array
Array of account objects that will receive this post
accounts[].id
string
Target social account ID
accounts[].scheduled_at
string
ISO 8601 time for scheduled post (omit for auto or recycle based on posting schedule)
...
...
All other post options (media, watermarks, signature, location, etc.) supported per post type
"recycle"Recurring posts are not supported in bulk scheduling.
/posts/schedule and monitor job status for completion.Authorization
Yes
Bearer-API YOUR_API_KEY
Publer-Workspace-Id
Yes
Workspace ID for scheduling posts
Content-Type
Yes
application/json
Accept
No
application/json (default)
bulk.state
string
Scheduling mode: "scheduled" (manual schedule), "auto", or "recycle"
bulk.posts
array
Array of up to 500 post objects
posts[].networks
object
Networks and their post data (e.g., Facebook, Mastodon, etc.)
posts[].networks.{network}
object
Post content for each targeted network
"weekly"
repeat_rate
integer
How often to repeat in the chosen interval.
For example, 6 with "weekly" means every 6 weeks.
6
days_of_week[]
array
For weekly repeats, which days to schedule on.
Values: [0, 1, 2, 3, 4, 5, 6]
[0,4]
Limited
Requires 10+ variations using Spintax Generator
Google Business Profile
Limited
Requires 10+ variations using Spintax Generator
YouTube
Not supported
API limitations
TikTok
Not supported
API limitations
WordPress
Not supported
API limitations
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1714558492{
"error": "Rate limit exceeded. Retry later."
}POST /api/v1/posts/schedule{
"bulk": {
"state": "scheduled",
"posts": [
{
"networks": {
"facebook": {
"type": "status",
"text": "Bulk Scheduling"
},
"mastodon": {
"type": "status",
"text": "Bulk Scheduling"
}
},
"accounts": [
{
"id": "63c675b54e299e9cf2b667ea"
},
{
"id": "650170394e299e33b427c2ff",
"scheduled_at": "2025-08-17T16:19+02:00"
}
]
},
{
"accounts": [
{
"id": "63c675b54e299e9cf2b667ea"
},
{
"id": "650170394e299e33b427c2ff",
"scheduled_at": "2025-07-17T17:19+02:00"
}
],
"networks": {
"facebook": {
"type": "status",
"text": "Second Post"
},
"mastodon": {
"type": "status",
"text": "Second Post"
}
}
},
{
"accounts": [
{
"id": "63c675b54e299e9cf2b667ea"
},
{
"id": "650170394e299e33b427c2ff",
"scheduled_at": "2025-06-17T18:19+02:00"
}
],
"networks": {
"facebook": {
"type": "status",
"text": "Third post"
},
"mastodon": {
"type": "status",
"text": "Third post"
}
}
}
]
}
}2025-06-05T13:29+02:002025-07-21T13:29+02:00to
string
Yes if from used
ISO date or datetime; include posts on/before this timestamp
page
integer
No
Page number (default: 0)
account_ids[]
array
No
List of account IDs to filter by
query
string
No
Full-text search keyword in post content
postType
string
No
Filter by post type (see Type Values below)
member_id
string
No
Filter posts created by a specific workspace member
Scheduled posts that are locked
published
All published posts
published_posted
Posts that were successfully published
published_deleted
Published posts that were deleted
published_hidden
Published posts that were hidden
draft
All draft posts
draft_dated
Draft posts with a scheduled date
draft_undated
Draft posts without a scheduled date
draft_private
Private draft posts
draft_public
Public draft posts
failed
Posts that failed to publish
recycling
All recycling posts
recycling_active
Active recycling posts
recycling_paused
Paused recycling posts
recycling_expired
Expired recycling posts
recycling_failed
Failed recycling posts
recycling_pending
Recycling posts pending approval
recycling_declined
Recycling posts that were declined
recycling_reauth
Recycling posts requiring account reauthorization
recycling_locked
Recycling posts that are locked
recurring
Recurring posts
Instagram or Facebook stories
short
YouTube shorts
poll
Poll posts
document
Document posts
carousel
Multi-image carousel posts
article
Article/blog posts
state
string
No
Filter by a single post state (see State Values below)
state[]
array
No
Filter by multiple post states
from
string
Yes if to used
Value
Description
all
All posts regardless of state
scheduled
All scheduled posts
scheduled_approved
Scheduled posts that have been approved
scheduled_pending
Scheduled posts pending approval
scheduled_declined
Scheduled posts that were declined
scheduled_reauth
Scheduled posts requiring account reauthorization
Value
Description
status
Text-only posts
link
Posts with links
photo
Photo posts
gif
GIF posts
video
Video posts
reel
Instagram or Facebook reels
ISO date or datetime; include posts on/after this timestamp
scheduled_locked
story
Telegram
Title, description
Native link preview
Mastodon
Title, description
Native link preview
Threads
Title, description
Native link preview
Bluesky
Title, description
Native link preview
networks.{provider}.link.title
string
Preview title (overrides fetched metadata)
networks.{provider}.link.description
string
Preview description (overrides fetched metadata)
networks.{provider}.link.images
array
Array of image URLs for the preview (overrides fetched metadata)
networks.{provider}.link.default_image
integer
Index (0-based) of the default image in the images array
networks.{provider}.link.call_to_action
string
CTA button type (e.g., LEARN_MORE, SIGN_UP)
accounts[].id
string
Target account identifier
accounts[].scheduled_at
string
ISO 8601 timestamp for scheduling (omit to publish immediately)
Set Caption
Add optional text to introduce or contextualize the link.
Choose Default Image
Use default_image to highlight your preferred preview image.
Schedule or Publish
For future posts: include scheduled_at under accounts.
For immediate posting: call /posts/schedule/publish or omit scheduled_at.
Title, description, images, CTA
Full link card support
Title, description, images, CTA
Full link card support
Twitter/X
Automatic card preview
Metadata driven by Twitter Card tags
Custom images
bulk.state
string
scheduled, publish, or a draft state
networks.{provider}.type
string
Must be "link"
networks.{provider}.text
string
Caption or message to accompany the link (optional)
networks.{provider}.link.url
string
The target URL
Requires uploaded images in media
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.
Advanced Scheduling Schedule per time zone or publish immediately; poll job status for completion.
Standard, Reels, Story
Standard: up to 5 h Reels: 3–90 s Stories: ≤60 s
< 2 GB
Flexible
Auto-captions, premiere scheduling
Feed, Reels, Story
Feed: any Reels: 3 s–15 min Stories: ≤60 s
Schedule a video post using the unified scheduling endpoint:
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 or from , when uploading.
networks.{provider}.media[].default_thumbnail
0-based index to select default thumbnail.
* Optional if you publish immediately via /posts/schedule/publish.
Upload Video Use the Media Handling 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.
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.
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).
Standalone photo update (no special details).
Promote an upcoming event with start/end times and an optional link.
Advertise discounts or promotions with coupon codes and terms.
networks.google.type
string
"photo"
networks.google.text
string
Main caption or description.
networks.google.title
string
CTA button label (LEARN_MORE, PROFILE, etc.).
networks.google.url
string
External URL (for events/offers).
Post Types
Updates, Photos, Events, Offers
Max Photo Size
5 MB
Min Photo Resolution
250 × 250 pixels
Call-to-Action Buttons
Supported (LEARN_MORE, PROFILE, etc.)
Events
Requires start and end fields
Offers
Supports coupon and terms
Select Profile
Choose the Google Business Profile in accounts[].id.
Choose Post Type
Update: general news with image & CTA.
Photo: standalone image.
Event: include details.type = "event", dates, and optional link.
Offer: include details.type = "offer", dates, coupon, and terms URL.
Add Media Upload or reference one photo via the .
Compose & Schedule
Build your JSON, set state and scheduled_at, then POST to /posts/schedule.
Use high-resolution images (≥250×250 pixels).
Craft clear CTAs to direct user action.
Include complete offer details (coupon & terms).
Set accurate event dates for reliable reminders.
Upload from URL
Once uploaded, you'll receive a media ID that can be referenced in your post requests.
Use this method when you have local media files that you want to upload directly.
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 Upload from URL method.
This endpoint expects a multipart/form-data request with the file included in the file field.
Key Response Fields
Field
Description
id
Unique identifier for the uploaded media (use this in post requests)
path
URL path to access the uploaded media
thumbnail
URL path to access a thumbnail version of the media
validity
Indicates which networks and post types support this media
width, height
Dimensions of the uploaded media in pixels
type
Media type (photo, video, document)
Use this method when your media is already hosted elsewhere and you want to import it by URL.
Request Parameters
Parameter
Description
Required
media[].url
URL of the media file to download
Yes
media[].name
Custom name for the media file
Yes
media[].caption
Caption for the media
No
media[].source
Source attribution
No
Unlike direct uploads, URL uploads are processed asynchronously. Use the returned job_id to check the status of your upload.
Once you've uploaded media and have the media ID, you can reference it in your post requests:
Supported formats: JPG, PNG, GIF, WEBP
Recommended dimensions: Varies by platform (see Networks Reference)
Maximum file size: Varies by platform, generally 5-10MB
Supported formats: MP4, MOV, AVI, WEBM
Recommended dimensions: Varies by platform (see Networks Reference)
Maximum file size: Varies by platform, generally 512MB-2GB
Duration limits: Varies by platform and content type
Supported formats: PDF
Maximum file size: 100MB
Supported networks: LinkedIn only
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.
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
Alt text: Always include descriptive alt text for accessibility
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
Duration: Keep videos under platform limits
Thumbnails: Consider uploading custom thumbnails for videos
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
Content Types - Details on different content formats
Network Reference - Platform-specific media requirements
Publishing Methods - Using media in different post types
Case‑insensitive search by competitor name.
from
date (YYYY-MM-DD)
No
Start date (inclusive).
to
date (YYYY-MM-DD)
No
End date (inclusive).
page
integer
No
Page number (0‑based). Default 0.
sort_by
string
No
One of: followers, reach, engagement, posts_count, videos_count, photos_count, links_count, statuses_count. Default followers.
sort_type
string
No
asc or desc. Default asc.
Start date (inclusive). Filters posts scheduled/published on or after this date.
to
date (YYYY-MM-DD)
Yes
End date (inclusive). Filters posts scheduled/published on or before this date.
query
string
No
Case-insensitive search across post text, title, link description, video title.
postType
string
No
Filter by post type. One of: poll, status, link, carousel, photo, gif, video, reel, document, short, article, story.
sort_by
string
No
Sort field. One of: scheduled_at, reach, engagement, engagement_rate, click_through_rate, reach_rate, postType, likes, video_views, comments, shares, saves, link_clicks, post_clicks. Default scheduled_at.
sort_type
string
No
Sort direction. ASC or DESC. Default DESC.
page
integer
No
Page number (0-based). Each page contains 10 posts. Default 0.
member_id
string
No
Filter by the workspace member who created the post.
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.
Send to the scheduling endpoint or use /posts/schedule/publish for immediate posting:
Upload: Use to upload vertical video (9:16).
Compose: Set "details.type": "reel", optional audio and feed flags.
Schedule: Provide scheduled_at or publish immediately.
Upload: Upload video ≤ 60 sec, 9:16 ratio.
Configure: Set "details.type": "short" and privacy.
Add Title/Text: Populate title and text.
Upload: Add photo or video ≤ 15 sec.
Tag as Story: Use "details.type": "story".
Caption: Add text overlay.
Use high-quality, platform-compliant media (9:16 ratio).
Rename Reel audio to match branding.
Schedule according to audience peak times.
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.
Authentication: Bearer API token
Scopes: posts, media
Headers:
Authorization: Bearer-API YOUR_API_KEY
Publer-Workspace-Id: YOUR_WORKSPACE_ID
Submit Request to /posts/schedule or /posts/schedule/publish
Receive { "job_id": "…" }
Poll /job_status/{job_id} until status: "completed"
All create requests share this shape:
bulk: batch container
state: how to handle content (see Publishing Methods)
posts: array of post definitions
networks: per-network content config
The state parameter determines how your content will be handled:
The type parameter specifies the content format:
Supported platforms and their keys under networks:
facebook, instagram, twitter, linkedin, pinterest, youtube, tiktok, google, wordpress_basic (self-hosted wordpress), wordpress_oauth (hosted on wordpress), telegram, mastodon, threads
Poll your job with:
Response:
To customize content for specific platforms:
Media files must be pre-uploaded and referenced by ID, see :
This overview covers the essential concepts for creating posts with the Publer API. For detailed information about specific features, refer to:
: Complete documentation of all publishing options
: Detailed guide to content formats and requirements
: Information about uploading and managing media
: Platform-specific capabilities and limitations
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.
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:
GET /api/v1/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"
}
]
}
]
}
}{
"bulk": {
"state": "scheduled",
"posts": [
{
"networks": {
"facebook": {
"type": "video",
"media": [
{
"id": "67da8532075cdb33821384c4",
"thumbnails": [
{
"id": "67da852b075cdb33821384ba",
"small": "https://.../thumb_67da852b075cdb33821384ba.jpg",
"real": "https://.../67da852b075cdb33821384ba.jpg"
},
......
{
"id": "67da852c075cdb33821384bb",
"small": "https://.../thumb_67da852c075cdb33821384bb.jpg",
"real": "https://.../67da852c075cdb33821384bb.jpg"
}
],
"title": "My Video Title",
"default_thumbnail": 1
}
],
"text": "Optional description or caption"
}
},
"accounts": [
{
"id": "YOUR_ACCOUNT_ID",
"scheduled_at": "2025-05-24T23:07:00+02:00"
}
]
}
]
}
}{
"bulk": {
"state": "scheduled",
"posts": [
{
"networks": {
"google": {
"type": "photo",
"text": "Our new feature is live!\npubler.com",
"title": "LEARN_MORE",
"media": [
{
"id": "68133d70f09cb4aa6377d2dc",
"path": "https://cdn.publer.com/uploads/photos/68133d70f09cb4aa6377d2dc.png",
"thumbnail": "https://cdn.publer.com/uploads/photos/thumb_68133d70f09cb4aa6377d2dc.png",
"type": "photo"
}
]
}
},
"accounts": [
{
"id": "GOOGLE_ACCOUNT_ID",
"scheduled_at": "2025-05-24T08:46:00-04:00"
}
]
}
]
}
}{
"bulk": {
"state": "scheduled",
"posts": [
{
"networks": {
"google": {
"type": "photo",
"details": { "type": "photo" },
"text": "Our office view today!",
"title": "PROFILE",
"media": [
{
"id": "68133d70f09cb4aa6377d2dc",
"path": "https://cdn.publer.com/uploads/photos/68133d70f09cb4aa6377d2dc.png",
"thumbnail": "https://cdn.publer.com/uploads/photos/thumb_68133d70f09cb4aa6377d2dc.png",
"type": "photo"
}
]
}
},
"accounts": [
{
"id": "GOOGLE_ACCOUNT_ID",
"scheduled_at": "2025-05-24T08:50:00-04:00"
}
]
}
]
}
}{
"bulk": {
"state": "scheduled",
"posts": [
{
"networks": {
"google": {
"type": "photo",
"details": {
"type": "event",
"title": "Summer Workshop",
"start": "2025-06-07T12:50:00Z",
"end": "2025-08-03T12:50:00Z"
},
"text": "Join our Summer Workshop series!",
"title": "LEARN_MORE",
"url": "https://publer.com/events",
"media": [
{
"id": "68133d70f09cb4aa6377d2dc",
"path": "https://cdn.publer.com/uploads/photos/68133d70f09cb4aa6377d2dc.png",
"thumbnail": "https://cdn.publer.com/uploads/photos/thumb_68133d70f09cb4aa6377d2dc.png",
"type": "photo"
}
]
}
},
"accounts": [
{
"id": "GOOGLE_ACCOUNT_ID",
"scheduled_at": "2025-06-07T08:50:00-04:00"
}
]
}
]
}
}{
"bulk": {
"state": "scheduled",
"posts": [
{
"networks": {
"google": {
"type": "photo",
"details": {
"type": "offer",
"title": "Spring Sale",
"start": "2025-05-28T12:50:00Z",
"end": "2025-10-02T12:50:00Z",
"coupon": "30%OFF",
"terms": "https://publer.com/terms"
},
"text": "Enjoy 30% off sitewide!",
"url": "https://publer.com/sale",
"media": [
{
"id": "68133d70f09cb4aa6377d2dc",
"path": "https://cdn.publer.com/uploads/photos/68133d70f09cb4aa6377d2dc.png",
"thumbnail": "https://cdn.publer.com/uploads/photos/thumb_68133d70f09cb4aa6377d2dc.png",
"type": "photo"
}
]
}
},
"accounts": [
{
"id": "GOOGLE_ACCOUNT_ID",
"scheduled_at": "2025-06-14T08:50:00-04:00"
}
]
}
]
}
}{
"bulk": {
"state": "scheduled",
"posts": [
{
"networks": {
"default": {
"type": "photo",
"text": "Check out our latest product!",
"media": [
{
"id": "6813892b5ec8b1e65235ae9e",
"type": "image",
"alt_text": "Product on white background"
}
]
}
},
"accounts": [
{
"id": "66db83154e299efa19a2d8eb",
"scheduled_at": "2025-05-15T14:30:00Z"
}
]
}
]
}
}networks.google.media[]
array
Array of 1 media object with keys: id, path, thumbnail, and type: "photo".
networks.google.details.type
string
One of: "photo", "event", "offer".
networks.google.details.title
string
Event or offer title (required for event/offer).
networks.google.details.start
string
ISO 8601 start date/time (for events/offers).
networks.google.details.end
string
ISO 8601 end date/time (for events/offers).
networks.google.details.coupon
string
Coupon code (offers only).
networks.google.details.terms
string
URL to terms & conditions (offers only).
accounts[].id
string
Google Business Profile account ID.
accounts[].scheduled_at
string
ISO 8601 timestamp for scheduling (omit for immediate publish).
Video Support
Not supported
< 1 GB
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
Standard
3 s–15 min
< 2 GB
1:2.4–2.4:1
Native profile/page posting
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).
media[].id
string
Publer media identifier
media[].path
string
URL to the video or image
media[].type
string
"video" or "photo"
media[].thumbnails
array
An array of thumbnail objects with id, small, and real URLs (Video only)
media[].default_thumbnail
integer
Index of the thumbnail image (Video only)
networks.{provider}.details
object
Format-specific settings
details.type
string
"reel", "short", or "story"
details.audio
string
Custom audio name for Reels (optional)
details.feed
boolean
true to also post Reel in Feed tab (Instagram only)
details.privacy
string
"public", "private", or "unlisted" (Shorts only)
accounts[].id
string
Target account identifier
accounts[].scheduled_at
string
ISO 8601 timestamp for scheduling (omit for immediate publishing)
Verify: Monitor job status and preview in dashboard.
Publish: Schedule or publish immediately.
scheduled_at or publish now.Reels
Instagram, Facebook
3–90 seconds
9:16
1 GB
Optional audio rename, feed toggle
Shorts
YouTube
≤ 60 seconds
9:16
2 GB
privacy: public/private/unlisted
Stories
Instagram, Facebook
≤ 15 seconds
9:16
1 GB
networks.{provider}.type
string
"video" for Reels/Shorts/Stories, "photo" for Stories
networks.{provider}.text
string
Caption or overlay text
networks.youtube.title
string
Title for YouTube Shorts
networks.{provider}.media[]
array
Media array (from Media API)
Photo or video, link stickers on IG
{
"bulk": {
"state": "scheduled",
"posts": [{
"networks": {
"instagram": {
"type": "video",
"text": "Our summer Reel!",
"media": [{
"id": "67c9630bedeb539dd87dd23c",
"path": "https://cdn.publer.com/videos/67c9630b.mp4",
"type": "video",
"thumbnails": [
{
"id": "67da852b075cdb33821384ba",
"small": "https://.../thumb_67da852b075cdb33821384ba.jpg",
"real": "https://.../67da852b075cdb33821384ba.jpg"
},
......
{
"id": "67da852c075cdb33821384bb",
"small": "https://.../thumb_67da852c075cdb33821384bb.jpg",
"real": "https://.../67da852c075cdb33821384bb.jpg"
},
"default_thumbnail": 1
}],
"details": {
"type": "reel",
"audio": "Custom audio name",
"feed": false
}
}
},
"accounts": [{
"id": "67d1f5f13d9895bab04393ec",
"scheduled_at": "2025-07-27T14:16:00+02:00"
}]
}]
}
}{
"bulk": {
"state": "scheduled",
"posts": [{
"networks": {
"youtube": {
"type": "video",
"title": "Our Latest Short",
"text": "Quick highlights!",
"media": [{
"id": "67c9630bedeb539dd87dd23c",
"path": "https://cdn.publer.com/videos/67c9630b.mp4",
"type": "video",
"thumbnails": [
{
"id": "67da852b075cdb33821384ba",
"small": "https://.../thumb_67da852b075cdb33821384ba.jpg",
"real": "https://.../67da852b075cdb33821384ba.jpg"
},
.....
{
"id": "67da852c075cdb33821384bb",
"small": "https://.../thumb_67da852c075cdb33821384bb.jpg",
"real": "https://.../67da852c075cdb33821384bb.jpg"
}
}],
"details": {
"type": "short",
"privacy": "public"
}
}
},
"accounts": [{
"id": "64abc34d4e299e662bfd6389",
"scheduled_at": "2025-08-01T14:16:00+02:00"
}]
}]
}
}{
"bulk": {
"state": "scheduled",
"posts": [{
"networks": {
"instagram": {
"type": "photo",
"text": "Behind the scenes!",
"media": [{
"id": "680fa5cc48487c4ccbf8c146",
"path": "https://cdn.publer.com/photos/680fa5cc.jpg",
"type": "photo"
}],
"details": {
"type": "story"
}
}
},
"accounts": [{
"id": "67d1f5f13d9895bab04393ec",
"scheduled_at": "2025-08-24T14:16:00+02:00"
}]
}]
}
}Handle results or errors
accounts: target profiles with scheduling overrides
Create repeating posts
recurring.repeat, recurring.days_of_week
Multi-image post
text, media array
pdf
PDF document (LinkedIn)
text, media array
blueskyEndpoint
Purpose
Result
/api/v1/posts/schedule
Schedule posts for future publication including drafts
Scheduled post or draft
/api/v1/posts/schedule/publish
Publish content immediately
Published post
/api/v1/job_status/{job_id}
Check status of submitted job
Job status
State
Description
Additional Parameters
scheduled
Schedule for specific date/time
scheduled_at (ISO timestamp)
draft, draft_private, draft_public
Save as draft
None required
scheduled + auto: true
Use AI-powered auto-scheduling
range.start_date, range.end_date
scheduled + recycling
Reuse content multiple times
recycling.gap, recycling.expire_count
Type
Description
Required Properties
status
Text-only post
text
photo
Image post
text, media array
video
Video post
text, media array
link
Link post with preview
text, url
recurring
carousel
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.
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.
bulk
state (e.g., "scheduled")
posts[]:
networks: { <network_name>: { type, text, details, ... } }
accounts[]:
id
scheduled_at (optional)
share (optional)
comments (optional array)
Use conditions to define when a callback should execute.
Structure:
conditions
relation: "AND" | "OR"
clauses:
age: { duration: number, unit: "Minute" | "Hour" | "Day" | "Week" }
engagements: { comparison: "gt" | "lt", value: number }
reach: { comparison: "gt" | "lt", value: number }
Notes:
age corresponds to "Is older than".
engagements and reach use comparison with "gt" (>) or "lt" (<).
A conditions object can include any subset of clauses; combine them using relation.
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)
share.account_ids order + delay determine spacing between shares
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.
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)
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)
Notes and behavior:
On Twitter/X, Mastodon, BlueSky, and Threads the follow-up comment will be posted as a new post in the thread.
Supported: Twitter/X, LinkedIn, Facebook Pages, Mastodon, Threads, BlueSky.
Not supported (API limitations): Pinterest, TikTok, Facebook Personal Profiles, Google Business Profiles.
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.
Example:
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
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)
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.
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).
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.
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.
Performance-based conditions depend on platform metrics; metrics may arrive with delay.
Content Types - Details on different content formats
Scheduled Posts - Information about scheduling posts
Immediate Publishing - How to publish content immediately
name
Original filename
type
Upload type (single or bulk)
No
direct_upload
Whether to upload directly to our S3 cloud (slower, but required if you need the final media URL)
(default: false)
No
in_library
Whether to save to media library (default: false)
No
Submit Request → Receive Job ID → Poll Job Status → Processing Complete{
"bulk": {
"state": "[publishing_method]",
"posts": [
{
"networks": {
"[network_provider]": {
"type": "[content_type]",
"text": "Post content",
// other network-specific fields
}
},
"accounts": [
{
"id": "ACCOUNT_ID"
// Additional parameters based on publishing method
}
],
// optional: recycling, recurring, labels, etc.
}
]
}
}GET /api/v1/job_status/{job_id}{
"status": "working|completed|failed",
"payload": { /* results or errors */ }
}{
"networks": {
"facebook": {
"type": "status",
"text": "Facebook simple status update"
},
"twitter": {
"type": "status",
"text": "Twitter/X specific content with #hashtags"
},
"linkedin": {
"type": "status",
"text": "Longer, more professional content for LinkedIn audience"
}
},
"accounts": [
{
"id": "66db83154e299efa19a2d8eb",
"scheduled_at": "2025-05-15T14:30:00Z"
},
{
"id": "66e973ac4e299e531f5dc034",
"scheduled_at": "2025-05-15T15:00:00Z"
},
{
"id": "66e973ac4e299e531f4hc034",
"scheduled_at": "2025-05-15T15:00:00Z"
}
]
}"media": [
{
"id": "66fba4234e299e531f5dc100",
"type": "image",
"alt_text": "Optional accessibility description"
}
]"share": {
"account_ids": ["A_ID_1", "A_ID_2"],
"text": "Check out our latest blog post!",
"conditions": {
"relation": "AND",
"clauses": {
"age": { "duration": 1, "unit": "Hour" },
"engagements": { "comparison": "gt", "value": 10 },
"reach": { "comparison": "gt", "value": 100 }
}
},
"delay": {
"duration": 0,
"unit": "Minute"
},
}"comments": [
{
"text": "First 100 customers get 10% off!",
"conditions": {
"relation": "AND",
"clauses": {
"age": { "duration": 2, "unit": "Hour" },
"engagements": { "comparison": "gt", "value": 10 },
"reach": { "comparison": "gt", "value": 10 }
}
}
},
{
"text": "24 hours left—don’t miss out!",
"conditions": {
"relation": "AND",
"clauses": {
"age": { "duration": 1, "unit": "Day" }
}
},
"media": {
"id": "680fa5cc48487c4ccbf8c146",
"path": ".../photos/680fa5cc48487c4ccbf8c146.jpg",
"thumbnail": ".../photos/thumb_680fa5cc48487c4ccbf8c146.jpg",
"caption": "Only one day left!"
}
}
]"delete": {
"conditions": {
"clauses": {
"age": { "duration": 7, "unit": "Day" },
"engagements": { "comparison": "lt", "value": 10 }
}
},
"hide": false
}{
"bulk": {
"state": "scheduled",
"posts": [
{
"networks": {
"facebook": {
"type": "status",
"text": "Your post content here"
}
},
"accounts": [
{
"id": "ACCOUNT_ID",
"scheduled_at": "2025-05-15T14:30:00Z", // Optional for immediate publishing
"share": { /* AutoShare config */ },
"comments":[ /* Follow-up comments */ ],
"delete": { /* Auto-Delete config */ }
}
]
}
]
}
}{
"bulk": {
"state": "scheduled",
"posts": [
{
"networks": {
"facebook": {
"type": "status",
"text": "Post with callbacks"
}
},
"accounts": [
{
"id": "63c675b54e299e9cf2b667ea",
"scheduled_at": "2025-10-31T10:23+01:00",
"share": {
"account_ids": [
"63c675b54e299e9cf2b667e8"
],
"conditions": {
"relation": "AND",
"clauses": {
"age": {
"duration": 10,
"unit": "Minute"
},
"engagements": {
"comparison": "gt",
"value": 10
},
"reach": {
"comparison": "gt",
"value": 100
}
}
},
"text": "AUTO SHARE"
},
"comments": [
{
"text": "FOLLOW UP COMMENT",
"conditions": {
"relation": "AND",
"clauses": {
"age": {
"duration": 10,
"unit": "Minute"
},
"engagements": {
"comparison": "gt",
"value": 10
},
"reach": {
"comparison": "gt",
"value": 100
}
}
}
},
{
"text": "OTHER COMMENT",
"conditions": {
"relation": "AND",
"clauses": {
"age": {
"duration": 10,
"unit": "Minute"
}
}
}
}
],
"delete": {
"conditions": {
"clauses": {
"age": {
"duration": 1,
"unit": "Hour"
}
}
},
"hide": false
}
}
]
}
]
}
}delete (optional)
networks.facebook.type
string
Must be "status".
networks.facebook.details
object
Facebook-specific settings.
networks.facebook.details.text_format_preset_id
string
ID of the background preset (see list below).
networks.facebook.text
string
Your post copy.
Use one of these text_format_preset_id values to select a background:
ID
Background Description
106018623298955
Solid purple, background
365653833956649
Pink tropical plants, background image
618093735238824
Brown illustration, background image
191761991491375
3D hearts, background image
2193627793985415
3D heart eyes emojis, background image
200521337465306
3D flame emojis, background image
No Other Media: Background posts cannot include images or videos.
Facebook Pages Only: Not supported on personal profiles or groups.
Links as Plain Text: URLs in your text appear without link previews.
Editing: You may change—but not remove—a background on published posts.
Character Limit: Publer allows unlimited text; Facebook enforces a 130-character cap on background posts.
Syncing: Background posts sync back as plain text, not background posts.
Select Complementary Backgrounds: Match your brand palette and message.
Keep Copy Concise: Short, punchy text reads best over busy backgrounds.
Preview Before Posting: Verify legibility and overall visual balance.
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.
Publer enables you to directly post or schedule TikTok videos and multi-photo posts (carousels) from your app or workflow.
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.
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.
To schedule or publish a TikTok post, use the or API endpoint with a networks.tiktok object describing your post.
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 .
Thumbnails (Videos): You can select a cover frame when posting automatically.
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.
No recurring or recycled posts: TikTok blocks duplicate content.
{
"bulk": {
"state": "scheduled",
"posts": [
{
"networks": {
"facebook": {
"type": "status",
"details": {
"text_format_preset_id": "1868855943417360"
},
"text": "Status update with background color\n\npubler.com"
}
},
"accounts": [
{
"id": "63c675b54e299e9cf2b667ea",
"scheduled_at": "2025-06-21T23:18:00+02:00"
}
]
}
]
}
}1821844087883360
Walking Yellow illustration, background image
177465482945164
Light purple 3D cube pattern, background image
160419724814650
Orange with Pink illustration, background image
248623902401250
3D smiling emoji background, background image
240401816771706
3D rose emojis, background image
1868855943417360
3D crying laughter emoji, background image
255989551804163
Eye Pink illustration, background image
1792915444087912
1792915444087912 illustration, background image
1654916007940525
Light grey illustration, background image
1679248482160767
Light blue illustration, background image
518948401838663
Pink heart pattern on pink background, background image
423339708139719
Illustration, background image
204187940028597
Solid red, background
621731364695726
Solid red, background
518596398537417
Red illustration, background image
134273813910336
Tree Red illustration, background image
217321755510854
Pink and purple hearts on a pink background, background image
323371698179784
Sunset Red illustration, background image
901751159967576
Gradient, dark orange red, background
552118025129095
Brown illustration, background image
263789377694911
Apple Red illustration, background image
606643333067842
Tulip Light orange illustration, background image
458988134561491
Cat Dark orange illustration, background image
548109108916650
Unicorn Red illustration, background image
175493843120364
Pink and yellow gradient, background image
338976169966519
Stairs Beige illustration, background image
206513879997925
Spiral Beige illustration, background image
168373304017982
Cube Beige illustration, background image
1271157196337260
Solid red, background
174496469882866
Lemon Yellow illustration, background image
862667370603267
Egg Light yellow illustration, background image
127541261450947
Ball Green illustration, background image
218067308976029
218067308976029 Light grey illustration, background image
688479024672716
Gradient, teal light green, background
238863426886624
Cat Light blue illustration, background image
301029513638534
Solid teal, background
154977255088164
Solid teal, background
1941912679424590
Gradient, grey dark grey, background
396343990807392
Flower Teal illustration, background image
143093446467972
Blue clouds on a dark blue background, background image
161409924510923
Rocket ship makes a heart in the sky, background image
145893972683590
Solid dark purple, background
217761075370932
Solid blue, background
931584293685988
Wave Blue illustration, background image
148862695775447
Pink and purple hearts on a purple background, background image
100114277230063
Deep Sea Blue illustration, background image
558836317844129
Spiral purple illustration, background image
172497526576609
Watermelon Light purple illustration, background image
433967226963128
Solid purple, background
197865920864520
Donut Light purple illustration, background image
643122496026756
Pink illustration, background image
762009070855346
Ballon Light grey illustration, background image
228164237768720
Grey heart pattern on a black background, background image
146487026137131
Rain Black illustration, background image
221828835275596
Glasses Light grey illustration, background image
1903718606535395
Solid red, background
1881421442117417
Solid black, background
249307305544279
Gradient, red blue, background
1777259169190672
Gradient, purple magenta, background
303063890126415
Yellow and orange and pink gradient, background image
122708641613922
Gradient, dark grey black, background
319468561816672
Dark blue illustration, background image
121945541697934
121945541697934 Pink illustration, background image
288211338285858
Blue illustration, background image
446330032368780
Gradient, red, background
219266485227663
Solid magenta, background
1289741387813798
Solid dark red, background
1365883126823705
Solid blue, background
status, photo, video, link, carousel, story, reel, gif
photo, video, carousel, story, reel
Twitter/X
status, photo, video, link, gif, poll
status, photo, video, link, document, poll, gif
photo, video, carousel
Google Business
status, photo, event, offer
YouTube
video, short
TikTok
video, photo, carousel
WordPress
article
Telegram
status, photo, video, link, gif
Mastodon
status, photo, video, link, gif, poll
Threads
status, photo, video, link
Bluesky
status, photo, video, link
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.
Follow each platform’s style and character limits for optimal engagement.
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).
Poll the job status endpoint to ensure the content was processed and published without errors.
Media Handling - Detailed guide for uploading and managing media
Network Reference - Platform-specific capabilities and limitations
Publishing Methods - Ways to publish different content types
Network
Supported Content Types
media[].id
string
Yes
Media ID if using stored media.
media[].path
string
No
URL to the video file.
media[].default_thumbnail
integer
No
(Optional) Index of the selected thumbnail (0-based).
media[].thumbnails[]
array
Yes
Array of thumbnails with real and small URLs.
media[].thumbnails[].real
string
No
Full-size thumbnail image URL.
media[].thumbnails[].small
string
No
Small-size thumbnail image URL.
details
object
Yes
TikTok-specific options (see below).
details.privacy
string
No
Who can view: "PUBLIC_TO_EVERYONE", "MUTUAL_FOLLOW_FRIENDS",
"FOLLOWER_OF_CREATOR", "SELF_ONLY"
details.comment
boolean
No
Allow comments (default: false).
details.duet
boolean
No
Allow duets (default: true).
details.stitch
boolean
No
Allow stitching (default: true).
details.promotional
boolean
No
Mark as promotional/brand organic content (cannot be private, default: false).
details.paid
boolean
No
Mark as paid partnership (cannot be private, default: false).
media[]
array
Yes
Up to 35 photo objects (see below).
media[].id
string
Yes
Media ID if using stored media.
media[].path
string
No
(Optional) URL to the photo file.
media[].caption
string
No
(Optional) Caption for each photo.
details
object
Yes
TikTok-specific options (see below).
details.privacy
string
No
Who can view: "PUBLIC_TO_EVERYONE", "MUTUAL_FOLLOW_FRIENDS",
"FOLLOWER_OF_CREATOR", "SELF_ONLY"
details.comment
boolean
No
Allow comments (default: false).
details.auto_add_music
boolean
No
Auto-add music to slideshow (default: false).
details.promotional
boolean
No
Mark as promotional/brand organic content (cannot be private, default: false).
details.paid
boolean
No
Mark as paid partnership (cannot be private, default: false).
details.reminder
boolean
No
Upload-only mode (user must publish manually, default: false).
Watermarks: Not supported.
Links: Not supported in TikTok posts.
type
string
Yes
Must be "video".
text
string
Yes
Video description text (max 2,200 chars).
media[]
array
Yes
type
string
Yes
Must be "photo".
title
string
Yes
Carousel post title (max 90 chars).
text
string
Yes
Single video object (see below).
Description text (max 4,000 chars).
{
"bulk": {
"state": "scheduled",
"posts": [
{
"accounts": [
{
"id": "tiktok_account_123",
"scheduled_at": "2025-08-26T12:00:00Z"
}
],
"networks": {
"tiktok": {
"type": "video",
"text": "Check out our new product launch! #launch #tiktok",
"media": [
{
"id": "media_video_001",
"path": "https://storage.com/launch-video.mp4",
"default_thumbnail": 2,
"thumbnails": [
{
"real": "https://storage.com/thumb1.jpg",
"small": "https://storage.com/thumb1_small.jpg"
},
{
"real": "https://storage.com/thumb2.jpg",
"small": "https://storage.com/thumb2_small.jpg"
},
{
"real": "https://storage.com/thumb3.jpg",
"small": "https://storage.com/thumb3_small.jpg"
}
]
}
],
"details": {
"privacy": "PUBLIC_TO_EVERYONE",
"comment": true,
"duet": true,
"stitch": true,
"promotional": false,
"paid": false,
"reminder": false
}
}
}
}
]
}
}{
"bulk": {
"state": "scheduled",
"posts": [
{
"accounts": [
{
"id": "tiktok_account_123",
"scheduled_at": "2025-08-26T14:00:00Z"
}
],
"networks": {
"tiktok": {
"type": "photo",
"title": "Summer Vibes ☀️",
"text": "Nothing beats a perfect summer day! What's your favorite summer activity? 🏖️ #summer #lifestyle #photography",
"media": [
{ "id": "img1", "path": "https://storage.com/summer1.jpg", "caption": "Beach day" },
{ "id": "img2", "path": "https://storage.com/summer2.jpg", "caption": "Sunset views" },
{ "id": "img3", "path": "https://storage.com/summer3.jpg", "caption": "Ice cream time" }
],
"details": {
"privacy": "PUBLIC_TO_EVERYONE",
"auto_add_music": true,
"comment": true,
"promotional": false,
"paid": false,
"reminder": false
}
}
}
}
]
}
}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.
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.
You can only post to Communities you have joined.
Community posts help foster deeper engagement on niche topics or interests.
To publish a post inside a Twitter/X Community via the API, you need:
The Community ID (found in the X Community URL: https://x.com/i/communities/{COMMUNITY_ID})
The Community Name (for reference and clarity)
Whether to share the post with followers or not
Set the community object inside the details for the twitter network configuration:
Go to the Community on X.
Look at the URL:
https://x.com/i/communities/1492410432069451776
The number at the end is your COMMUNITY_ID.
Membership Required: You must be a member of the Community to post.
Engagement: Only members can engage with Community posts, but all users can view them.
Visibility: Community posts are public, but participation is limited to members.
Scheduling: You can schedule Community posts just like any other X post using Publer.
Join Relevant Communities: Ensure your X account has joined the Communities you wish to post in.
Use for Focused Engagement: Target posts to specific Communities for more relevant discussions.
Check Community Guidelines: Each Community may have its own moderation and content rules.
networks.twitter.details.community.id
string
Community ID (from the Community URL)
networks.twitter.details.community.name
string
Name of the Community (optional, for clarity in requests/logs)
networks.twitter.details.community.share_with_followers
boolean
Whether to share the post with followers or not (defaulted to true)
{
"bulk": {
"state": "scheduled",
"posts": [
{
"networks": {
"twitter": {
"type": "status",
"details": {
"community": {
"id": "1508851391443484686",
"share_with_followers": true,
"name": "ALBANIANS"
}
},
"text": "Post to X communities"
}
},
"accounts": [
{
"id": "66e011b94e299eb49376c715",
"scheduled_at": "2025-07-03T10:28+02:00"
}
]
}
]
}
}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
Send your post to networks right away.
Endpoint:
Request example:
Omit scheduled_at entirely
Content is processed immediately via the schedule/publish endpoint
Supports all content types and network-specific options
Plan posts for future dates and times across multiple networks.
Endpoint:
Request example:
Include a valid ISO 8601 scheduled_at timestamp
Times must be at least 1 minute in the future
Supports timezone offsets
Each account can have its own scheduled_at
Save work-in-progress content for review or refinement.
Endpoint:
Request example (private draft):
State Value
Description
Access Control
draft_private
Private draft
Only accessible to the creator
draft_public or draft
Workspace-visible draft
Available to all workspace members with appropriate permissions
Let Publer pick the best posting times within a date range.
Endpoint:
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:
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
Automatically repost content multiple times on a defined cadence.
Endpoint:
First, you need to create a post and a posting schedule. Click here to learn how to set up a new time slot for your posts.
Request example:
Key recycling parameters:
Parameter
Type
Description
recycling.solo
boolean
When true, recycles as individual post; otherwise groups with other recycled content
recycling.gap
number
Frequency number (1, 2, 3, etc.)
recycling.gap_freq
string
Frequency unit (Day, Week, or Month)
recycling.start_date
string
Date to begin recycling (ISO 8601 format)
Schedule content to repeat on a predefined pattern.
Endpoint:
Request example:
Parameter
Type
Required
Description
state
string
Yes
Must be set to recurring
recurring.start_date
string
Yes
First occurrence date (ISO 8601 format)
recurring.end_date
string
No
Last occurrence date (ISO 8601 format)
All publishing methods return a job ID for asynchronous processing:
Always verify success by checking the job status:
Example success response:
Status
Description
Next Action
working
Job is still being processed
Wait and check again
complete
Job finished (check failures object for partial failures)
Review results
failed
Job failed completely
Check error details and retry
Network-specific content: Override content for specific platforms
Multi-account publishing: Target multiple accounts in a single request
POST /api/v1/posts/schedule/publish{
"bulk": {
"state": "scheduled",
"posts": [
{
"networks": {
"facebook": {
"type": "status",
"text": "Breaking news update!"
}
},
"accounts": [
{
"id": "66db83154e299efa19a2d8eb"
// No scheduled_at parameter
}
]
}
]
}
}POST /api/v1/posts/schedule{
"bulk": {
"state": "scheduled",
"posts": [
{
"networks": {
"facebook": {
"type": "status",
"text": "Scheduled announcement for next week!"
}
},
"accounts": [
{
"id": "66db83154e299efa19a2d8eb",
"scheduled_at": "2025-05-15T14:30:00Z"
}
]
}
]
}
}POST /api/v1/posts/schedule{
"bulk": {
"state": "draft_private",
"posts": [
{
"networks": {
"facebook": {
"type": "status",
"text": "Draft post for later review"
}
},
"accounts": [
{
"id": "66f509f7db2797026a37ba76"
}
]
}
]
}
}POST /api/v1/posts/schedule{
"bulk": {
"state": "scheduled",
"posts": [
{
"networks": {
"facebook": {
"type": "status",
"text": "Autoschedule post"
}
},
"accounts": [
{
"id": "66f509f7db2797026a37ba76"
}
],
"share_next": false,
"range": {
"start_date": "2025-05-23T07:45:00.000Z",
"end_date": "2025-05-31T07:45:00.000Z"
},
"auto": true
}
]
}
}POST /api/v1/posts/schedule{
"bulk": {
"state": "scheduled",
"posts": [
{
"networks": {
"default": {
"type": "status",
"text": "This content will be recycled multiple times"
}
},
"accounts": [
{
"id": "66f509f7db2797026a37ba76",
"labels": [""]
}
],
"range": {
"start_date": "2025-05-23T07:45:00.000Z",
"end_date": null
},
"recycling": {
"solo": true,
"gap": 2,
"gap_freq": "Week",
"start_date": "2025-06-01",
"expire_count": "3",
"expire_date": "2025-07-15"
}
}
]
}
}POST /api/v1/posts/schedule{
"bulk": {
"state": "recurring",
"posts": [
{
"networks": {
"default": {
"type": "status",
"text": "Weekly update post"
}
},
"accounts": [
{
"id": "66f509f7db2797026a37ba76"
}
],
"recurring": {
"start_date": "2025-05-01T03:45-04:00",
"end_date": "2025-06-01T03:45-04:00",
"repeat": "weekly",
"days_of_week": [1, 5],
"repeat_rate": 1
}
}
]
}
}{
"job_id": "6810dec617eae6d55d7a5e5b"
}GET /api/v1/job_status/6810dec617eae6d55d7a5e5b{
"status": "complete",
"payload": {
"failures": {}
},
"plan": {
// Current user's plan details
}
}share_next
boolean
No
When true, uses next available optimal slot
recycling.expire_count
string or number
Maximum number of times to recycle
recycling.expire_date
string
Date to stop recycling (ISO 8601 format, alternative to count)
recurring.repeat
string
Yes
Frequency type: daily, weekly, or monthly
recurring.days_of_week
array
For weekly
Array of weekdays (1=Monday, 7=Sunday)
recurring.repeat_rate
number
No
How often to repeat (e.g., 1=every week, 2=every other week)
recurring.time
string
No
Fixed time for posts (format: "HH:MM")
Authorization: Bearer-API YOUR_API_KEYPubler-Workspace-Id: YOUR_WORKSPACE_ID
Retrieve aggregated analytics for hashtags used in published posts. Supports filtering by date range, account, member, and search, plus sorting and pagination.
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.
account_id
string
No
Limit to a single social account. Omit for all workspace accounts.
from
date (YYYY-MM-DD)
No
Start date (inclusive).
to
date (YYYY-MM-DD)
No
End date (inclusive).
sort_by
string
No
Fields:
records[]: One row per hashtag.
hashtag: Text without #.
posts: Number of posts using it.
recent_posts[]: Up to 3 recent posts { id, text, scheduled_at }.
Totals: reach, likes, comments, shares, engagement, video_views, link_clicks, post_clicks, saves.
hashtag_score (%): Relative performance = (total hashtag engagement / total post engagement) × 100.
total: Total hashtags matching filters.
Retrieve up to 6 top posts that used a specific hashtag, with full per‑post analytics.
account_id
string
No
Limit to a single social account. Omit for all workspace accounts.
hashtag
string
Yes
Hashtag to analyze (with #).
from
date (YYYY-MM-DD)
No
Start date (inclusive).
to
date (YYYY-MM-DD)
No
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.
Platform differences: Metrics availability varies by social network/account type; missing fields may be null or omitted.
Pagination (insights list): page is 0‑based and returns 10 hashtags per page.
Hashtag score: hashtag_score (%) = (total hashtag engagement / total post engagement) × 100.
Post Insights — Per‑post performance analytics
Charts — Discover chart IDs and fetch chart data
Best Times — Suggested posting time slots
Members — Member (team) analytics
GET /api/v1/analytics/:account_id/hashtag_insightsGET /api/v1/analytics/hashtag_performing_postsOne of: posts, reach, likes, comments, shares, video_views. Default posts.
sort_type
string
No
ASC or DESC. Default DESC.
page
integer
No
Page number (0‑based). Each page contains 10 hashtags. Default 0.
query
string
No
Case‑insensitive filter by hashtag text.
member_id
string
No
Filter hashtags by posts authored/managed by a member.
End date (inclusive).
sort_by
string
No
One of: scheduled_at, reach, engagement, engagement_rate, click_through_rate, reach_rate, postType, likes, video_views, comments, shares, saves, link_clicks, post_clicks. Default scheduled_at.
sort_type
string
No
ASC or DESC. Default DESC.
member_id
string
No
Filter by post author/manager.
query
string
No
Text search in post text/title/link info.
Detailed platform-specific capabilities, content support, and limitations for all social networks available via the Publer API.
Network
Provider
Content Types
Media Support
Character Limit
Provider: facebook
Content Types:
Text posts
Text posts with background color
Photo posts (single or multiple)
Video posts
Limitations:
Text: 10,000 characters
Photos: Up to 10 per post
Videos: Up to 240 minutes, 10GB max file size
Link previews: Automatically generated from URL
Special Considerations:
Page permissions required for business pages
Video aspect ratio: 16:9 to 9:16 supported
Image aspect ratio: 1.91:1 to 1:1 recommended
Hashtags supported but used less frequently than other platforms
Example:
Provider: instagram
Content Types:
Photo posts (single or multiple)
Video posts
Carousel posts
Stories
Limitations:
Text (caption): 2,200 characters
Photos: Up to 10 per carousel
Videos: Up to 60 minutes, 10GB max file size
Stories: 15 seconds per segment
Special Considerations:
Business account required for API posting
Image aspect ratio: Between 1.91:1 and 4:5 (square 1:1 recommended)
Cannot post links in captions (they won't be clickable)
First comments can be auto-posted with hashtags
Example:
Provider: twitter
Content Types:
Text posts
Photo posts (single or multiple)
Video posts
Link posts
Limitations:
Text: 280 characters (25,000 for premium accounts)
Photos: Up to 4 per tweet
Videos: Up to 140 seconds for standard users
URLs count as 23 characters regardless of length
Special Considerations:
Developer account required for API access
Hashtags and @mentions count toward character limit
Media attachments no longer count toward the 280 character limit
Alt text for images highly recommended
Example:
Provider: linkedin
Content Types:
Text posts
Photo posts
Video posts
Link posts
Limitations:
Text: 3,000 characters
Photos: Up to 9 per post
Videos: Up to 15 minutes, 5GB max file size
Documents: PDF format, 100MB max
Special Considerations:
Supports markdown-style formatting (bold, italic, bullets)
Company page access requires admin privileges
More formal tone typically recommended
Professional content performs best
Example:
Provider: pinterest
Content Types:
Photo pins
Video pins
Limitations:
Description: 500 characters
Images: 20MB max, 1000x1500px recommended
Videos: 30 seconds minimum, 15 minutes maximum
Special Considerations:
Must include an image or video (no text-only posts)
Vertical images (2:3 ratio) perform best
Board selection required when posting
Alt text important for search optimization
Example:
Provider: google
Content Types:
Text posts
Photo posts
Video posts
Link posts
Limitations:
Text: 1,500 characters
Photos: Up to 10 per post
Videos: Up to 30 seconds
Special Considerations:
Location ID required for multi-location businesses
Posts expire after 7 days by default
Call-to-action buttons available (Learn more, Book, Order, etc.)
Location-specific content recommended
Example:
Provider: tiktok
Content Types:
Video posts
Single or multi-photo/carousel posts
Limitations:
Caption: 2,200 characters
Videos: 3 seconds to 10 minutes
File size: 500MB maximum
Carousels can be up to 10 photos. At the moment, videos cannot be included in a carousel post.
Special Considerations:
Business account required for API posting
Vertical video format (9:16) required
Sound/music highly recommended
Cannot edit video after posting
Example:
Provider: youtube
Content Types:
Video posts
Shorts
Limitations:
Title: 100 characters
Description: 5,000 characters
Tags: Up to 500 characters total
Videos: Up to 12 hours, 256GB maximum
Special Considerations:
Channel verification required for longer videos
Thumbnail image can be specified
Category selection required
Privacy setting options (public, private, unlisted)
Example:
Provider: telegram
Content Types:
Text posts
Photo posts
Video posts
Link posts
Limitations:
Text: 4,096 characters per message
Photos: Up to 10 per post
Videos: Up to 2GB per file
File attachments: Up to 2GB
Special Considerations:
Bot API token required
Channel or group specified by chat ID
Markdown and HTML formatting supported
Silent posting option available
Example:
Provider: mastodon
Content Types:
Text posts
Photo posts
Video posts
Link posts
Limitations:
Text: 500 characters minimum (varies by server)
Photos: Up to 4 per post
Videos: Format and size limits vary by server
GIFs need to be less than 8 MB and have a resolution up to 1280x720 pixels.
Special Considerations:
Instance URL required for posting
Content warnings can be specified
Visibility options: public, unlisted, private, direct
Alt text essential for accessibility
Example:
Provider: threads
Content Types:
Text posts
Photo posts
Video posts
Limitations:
Text: 500 characters
Photos: Up to 10 per post
Videos: Up to 5 minutes
Special Considerations:
Requires Instagram business account connection
Cannot schedule posts for specific times via API
No direct link posting (links are non-clickable)
Hashtags supported but used differently than Instagram
Example:
Provider: bluesky
Content Types:
Text posts
Photo posts
Limitations:
Text: 300 characters
Photos: Up to 4 per post
Special Considerations:
Decentralized platform in beta stage
API access requires developer invitation
Custom domains and handles supported
Limited media format support
Example:
Cross-Platform Posting
Provide network-specific overrides under networks for optimal formatting.
Adjust media dimensions to each platform’s specs.
Tailor text length to char limits.
- Detailed information about different content formats
- Guide to uploading and managing media files
- Options for publishing to different networks
Carousel posts
Stories
GIFs limited to 15MB
1200x627px
1.91:1
5MB
1000x1500px
2:3
20MB
Google Business
1200x900px
4:3
5MB
Telegram
1280x720px
16:9
10MB
Mastodon
1200x900px
4:3
Server dependent
Threads
1080x1080px
1:1 to 4:5
8MB
Bluesky
1200x675px
16:9
5MB
16:9
0.5s - 140s
512MB
1920x1080px
16:9
3s - 15m
5GB
1080x1920px
9:16
4s - 15m
2GB
TikTok
1080x1920px
9:16
3s - 10m
500MB
YouTube
1920x1080px
16:9
No minimum - 12h
256GB
Telegram
1280x720px
16:9
No limits
2GB
Threads
1080x1920px
9:16
3s - 5m
650MB
Platform Selection
Choose networks based on audience and content type.
Leverage visual platforms (Instagram, Pinterest) for images/video-heavy campaigns.
Use LinkedIn for professional announcements; Facebook/Instagram for broad reach.
Error Prevention
Pre-validate media compatibility via upload responses’ validity flags.
Poll job status to catch and handle errors early.
facebook
status, photo, video, link, carousel
Images, videos, links
10,000
instagram
photo, video, carousel, story, reel
Images, videos
2,200
Twitter/X
twitter
status, photo, video, link
Images, videos, links, polls
280 (25,000 for premium)
linkedin
status, photo, video, link, document, polls
Images, videos, documents, links
3,000
pinterest
photo, video
Images, videos, links
500
Google Business
google
status, photo, video, link
Images, videos, links
1,500
TikTok
tiktok
video, single or multi-photo/carousel posts
Videos
2,200
YouTube
youtube
video, shorts
Videos
No fixed limit (100 chars min)
Telegram
telegram
status, photo, video, link
Images, videos, links
4,096
Mastodon
mastodon
status, photo, video, link, polls, gif
Images, videos, links
500+ (server dependent)
Threads
threads
status, photo, video
Images, videos
500
Bluesky
bluesky
status, photo, video
Images, videos
300
Network
Optimal Dimensions
Aspect Ratio
Max File Size
1200x630px
1.91:1
8MB
1080x1080px
1:1 to 4:5
8MB
1200x675px
16:9
5MB
Network
Optimal Dimensions
Aspect Ratio
Duration
Max File Size
1280x720px
16:9
1s - 240m
10GB
1080x1920px
9:16
3s - 60m
650MB
1280x720px
"facebook": {
"type": "status",
"text": "Facebook-specific content with more detailed formatting"
}"instagram": {
"type": "carousel",
"text": "Instagram caption with #hashtags",
"media": [
{"id": "media_id_1", "type": "image"},
{"id": "media_id_2", "type": "image"}
]
}"twitter": {
"type": "status",
"text": "Concise Twitter post with #hashtags and @mentions"
}"linkedin": {
"type": "status",
"text": "**Professional announcement** with formatted text:\n\n• Point one\n• Point two\n• Point three"
}"pinterest": {
"type": "photo",
"text": "Pin description with #hashtags",
"board_id": "board_id_here",
"media": [{"id": "media_id", "type": "image"}]
}"google": {
"type": "status",
"text": "Local business update with important information",
"location_id": "location_id_here",
"cta": {
"type": "LEARN_MORE",
"url": "https://example.com/details"
}
}"tiktok": {
"type": "video",
"text": "Caption with #hashtags #fyp",
"media": [{"id": "video_id", "type": "video"}]
}"youtube": {
"type": "video",
"text": "Video description with timestamps and links",
"title": "Video Title Here",
"media": [{"id": "video_id", "type": "video"}],
"privacy": "public",
"category": "22" // People & Blogs category
}"telegram": {
"type": "status",
"text": "Telegram message with *bold* and _italic_ formatting",
"disable_notification": false
}"mastodon": {
"type": "status",
"text": "Mastodon post with #hashtags",
"visibility": "public",
"content_warning": "Optional content warning"
}"threads": {
"type": "status",
"text": "Threads update with conversational tone"
}"bluesky": {
"type": "status",
"text": "Bluesky post with limited characters but #tags",
"media": [{"id": "image_id", "type": "image"}]
}Retrieves information about the currently authenticated user.
API key authentication. Format: "Bearer-API YOUR_API_KEY"
Successful operation
Unauthorized
Permission denied or missing required scope
Retrieves a list of all workspaces that the authenticated user has access to.
API key authentication. Format: "Bearer-API YOUR_API_KEY"
Successful operation
Unauthorized
Permission denied or missing required scope
Retrieves albums and watermarks for specified accounts in a workspace.
API key authentication. Format: "Bearer-API YOUR_API_KEY"
ID of the workspace to retrieve media options from
Array of account IDs to filter media options by
Successful operation
Unauthorized
Permission denied
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.
API key authentication. Format: "Bearer-API YOUR_API_KEY"
Array of post IDs to delete. Can include both MongoDB ObjectIDs and PostgreSQL IDs.
ID of the workspace containing the posts
Posts deleted successfully
Unauthorized
Permission denied or missing required scope
Retrieves a list of social media accounts available in the specified workspace.
API key authentication. Format: "Bearer-API YOUR_API_KEY"
ID of the workspace to retrieve accounts from
Successful operation
Unauthorized
Permission denied or missing required scope
Retrieves signatures associated with specified accounts in a workspace.
API key authentication. Format: "Bearer-API YOUR_API_KEY"
ID of the workspace to retrieve signatures from
Array of account IDs to filter signatures by
Successful operation
Unauthorized
Permission denied or missing required scope
Updates an existing post. The behavior differs depending on whether the post is already published or not.
API key authentication. Format: "Bearer-API YOUR_API_KEY"
ID of the post to update
ID of the workspace containing the post
Post updated successfully
Unauthorized
Forbidden - You cannot update a post that has been published with approval
Unprocessable Entity - Error message explaining why the post couldn't be updated
Retrieves analytics data for workspace members showing their posting activity and engagement metrics.
Start date for analytics data range (YYYY-MM-DD format). Filters data from this date onwards
{"value":"2024-01-01"}End date for analytics data range (YYYY-MM-DD format). Filters data up to this date
{"value":"2024-12-31"}Optional account ID to filter analytics data for a specific social media account
{"value":"63c675b54e299e9cf2b667ea"}ID of the workspace to retrieve members from
Members analytics data with performance metrics
Unauthorized
Permission denied - requires analytics access or paying subscription
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.
API key authentication. Format: "Bearer-API YOUR_API_KEY"
Specific media IDs to retrieve. If provided, pagination and other filters are ignored
Page number for pagination (0-based)
Filter by used status
Search term to filter media by name or caption
ID of the workspace to retrieve media from
Successful operation
Unauthorized
Permission denied or missing required scope
Search and retrieve Facebook locations based on a query string.
Search query for Facebook locations
List of Facebook locations matching the search query
Authentication failure or invalid token
Invalid request or Facebook API error
Search and retrieve Instagram locations based on a query string.
Search query for Instagram locations
List of Instagram locations matching the search query
Authentication failure, invalid token, or no Instagram account with Facebook login
Invalid request or Instagram API error
Search and retrieve Threads locations based on a query string.
Search query for Threads locations
List of Threads locations matching the search query
Authentication failure, invalid token, or no Threads account
Invalid request or Threads API error
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.
Social media account ID to analyze posting times for. When provided, analysis is specific to this account's performance data
Include competitor data in best times analysis. Set to 'true' to analyze competitor posting patterns
Specific competitor ID to analyze. Used in conjunction with competitors=true parameter
Start date for analytics data range (YYYY-MM-DD format). Filters data from this date onwards
{"value":"2024-01-01"}End date for analytics data range (YYYY-MM-DD format). Filters data up to this date
{"value":"2024-12-31"}ID of the workspace to retrieve best times from
Best times to post data organized by day of the week and hour for the specific account
Unauthorized
Permission denied - requires analytics access or paying subscription
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).
Social media platform type to filter charts for (e.g., 'ig_business', 'fb_page', 'twitter', 'linkedin', 'youtube', 'tiktok', 'google', 'pin_business')
ID of the workspace to retrieve charts from
List of available charts with metadata
Unauthorized
Permission denied or missing required scope
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.
Optional account ID to filter analytics data for a specific social media account
Array of chart IDs to retrieve data for. Use chart IDs from the /analytics/charts endpoint
{"value":["followers","post_engagement","post_reach"]}Start date for analytics data (YYYY-MM-DD format)
End date for analytics data (YYYY-MM-DD format)
ID of the workspace to retrieve data from
Analytics chart data with current and previous period values
Unauthorized
Permission denied or missing required scope
Retrieves a list of competitor accounts for the workspace or for a specific social media account.
ID of the social media account to retrieve competitors for.
ID of the workspace to retrieve competitors from
Successful operation
Unauthorized
Permission denied or missing required scope
Retrieves analytics data for competitor accounts, including engagement metrics, follower counts, and post performance statistics.
ID of the social media account to filter competitors analytics for
Specific competitor account ID to analyze
Search filter for competitor account names
Start date for analytics data (ISO 8601 format, e.g., 2023-01-01)
End date for analytics data (ISO 8601 format, e.g., 2023-12-31)
Page number for pagination (default: 0)
Field to sort results by
Sort direction
ID of the workspace to retrieve competitors analytics from
Successful operation
Unauthorized
Permission denied - requires analytics access or paying subscription
Unprocessable entity - service error
Retrieves comprehensive analytics data for published posts with advanced filtering, sorting, and pagination capabilities.
Filter posts for a specific social media account ID. If omitted, includes all workspace accounts. Used with competitors parameter for competitor-specific analysis
Include competitor analysis data. Set to 'true' to retrieve competitor post insights
Specific competitor account ID to analyze when competitors=true. Works in conjunction with account_id parameter
Start date for post insights data range (YYYY-MM-DD format). Filters posts scheduled on or after this date
{"value":"2024-01-01"}End date for post insights data range (YYYY-MM-DD format). Filters posts scheduled on or before this date
{"value":"2024-12-31"}Search query to filter posts by text content, title, link description, or video title using case-insensitive matching
Filter posts by specific post type (e.g., image, video, link, text, carousel)
Field to sort results by. Supports various engagement and performance metrics
Sort order direction
Page number for pagination (0-based indexing). Each page contains 10 posts
Filter posts by specific workspace member/user ID who created or manages the posts
ID of the workspace to retrieve insights from
Post insights data with analytics metrics and pagination information
Unauthorized
Permission denied - requires analytics access or paying subscription
Retrieves a list of posts based on the specified filters.
API key authentication. Format: "Bearer-API YOUR_API_KEY"
Filter by post state
Available options:
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
Filter posts scheduled/published after this date
Required if to is provided
Filter posts scheduled/published before this date
Required if from is provided
Page number for pagination
Filter posts by multiple account IDs
Search query to filter posts by content
Filter by post type
Available options:
status, link, photo, gif, video, reel, story, short, poll, document, carousel, article
Filter posts by team member ID
ID of the workspace to retrieve posts from
Successful operation
Unauthorized
Permission denied or missing required scope
Extracts metadata from a URL including title, description, images, and more. Useful for previewing links before creating a post.
API key authentication. Format: "Bearer-API YOUR_API_KEY"
The URL to extract metadata from
Successful operation
Unauthorized
Unprocessable Entity - Invalid URL
Upload a media file (image, video, or document) to be used in social media posts
API key authentication. Format: "Bearer-API YOUR_API_KEY"
ID of the workspace to upload media
Whether to upload directly to our S3 cloud (slower, but required if you need the final media URL)
falseWhether to save to media library
falseMedia file uploaded successfully
Invalid request parameters
Unauthorized
Permission denied or missing required scope
Upload media files by providing URLs
API key authentication. Format: "Bearer-API YOUR_API_KEY"
ID of the workspace to upload media
Upload type
singlePossible values: Whether to upload directly to our S3 cloud (slower, but required if you need the final media URL)
falseWhether to save to media library
falseMedia upload job created successfully
Invalid request parameters
Unauthorized
Permission denied or missing required scope
Check the status of an asynchronous job, including URL media uploads
API key authentication. Format: "Bearer-API YOUR_API_KEY"
ID of the job to check
ID of the workspace to retrieve posts from
Job status retrieved successfully
Unauthorized
Permission denied or missing required scope
Schedule one or more posts for publishing. Supports immediate publishing, scheduled publishing, auto-scheduling, recurring posts, and more.
API key authentication. Format: "Bearer-API YOUR_API_KEY"
ID of the workspace to schedule posts in
Posts scheduled successfully
Invalid scheduling parameters
Unauthorized
Permission denied or missing required scope
Creates a new social media post. Can be scheduled for immediate publishing, future publishing, or saved as a draft.
API key authentication. Format: "Bearer-API YOUR_API_KEY"
ID of the workspace to create post in
Post creation job initiated
Invalid post data
Unauthorized
Permission denied or missing required scope
Check the status of an asynchronous job, including URL media uploads
API key authentication. Format: "Bearer-API YOUR_API_KEY"
ID of the job to check
ID of the workspace to retrieve posts from
Job status retrieved successfully
Unauthorized
Permission denied or missing required scope
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.
Filter hashtags for a specific social media account ID. If omitted, includes all workspace accounts
Start date for hashtag insights data range (YYYY-MM-DD format). Filters posts scheduled on or after this date
{"value":"2024-01-01"}End date for hashtag insights data range (YYYY-MM-DD format). Filters posts scheduled on or before this date
{"value":"2024-12-31"}Field to sort hashtag results by. Supports various engagement and performance metrics
Sort order direction
Page number for pagination (0-based indexing). Each page contains 10 hashtags
Search query to filter hashtags by name using case-insensitive matching
Filter hashtags by specific workspace member ID
ID of the workspace to retrieve insights from
Hashtag insights data with analytics metrics and pagination information
Unauthorized
Permission denied - requires analytics access or paying subscription
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.
Filter posts for a specific social media account ID. If omitted, includes all workspace accounts
The hashtag to retrieve performing posts for (with # symbol). This parameter is required to filter posts by the specific hashtag
{"value":"socialmedia"}Start date for posts data range (YYYY-MM-DD format). Filters posts scheduled on or after this date
{"value":"2024-01-01"}End date for posts data range (YYYY-MM-DD format). Filters posts scheduled on or before this date
{"value":"2024-12-31"}Field to sort post results by. Supports various engagement and performance metrics
Sort order direction
Filter posts by specific workspace member ID
Search query to filter posts by content text, title, or link information using case-insensitive matching
ID of the workspace to retrieve posts from
Hashtag performing posts data with analytics metrics
Unauthorized
Permission denied - requires analytics access or paying subscription
{
"id": "5b1ec026db27977424e8599e",
"email": "[email protected]",
"name": "ervintorra",
"first_name": "Ervin",
"picture": "https://publer-dev.s3.amazonaws.com/uploads/photos/thumb_mini_magick20250123-28707-otuw0w.png"
}GET /api/v1/users/me HTTP/1.1
Host: app.publer.com
Authorization: YOUR_API_KEY
Accept: */*
[
{
"id": "61a7c2e4f9e8c3b2d1e0f9a8",
"owner": {
"id": "5b1ec026db27977424e8599e",
"email": "[email protected]",
"name": "ervintorra",
"first_name": "Ervin",
"picture": "https://publer-dev.s3.amazonaws.com/uploads/photos/thumb_mini_magick20250123-28707-otuw0w.png"
},
"name": "Marketing Team",
"members": [
{}
],
"plan": "business",
"picture": "https://publer-dev.s3.amazonaws.com/uploads/logos/marketing_team_logo.png"
}
]GET /api/v1/workspaces HTTP/1.1
Host: app.publer.com
Authorization: YOUR_API_KEY
Accept: */*
[
{
"id": "text",
"albums": [
{
"id": "text",
"name": "text",
"type": "text"
}
],
"watermarks": [
{
"id": "text",
"name": "text",
"opacity": 1,
"size": 1,
"position": "text",
"default": true,
"image": "text"
}
]
}
]GET /api/v1/workspaces/{workspace_id}/media_options?accounts=text HTTP/1.1
Host: app.publer.com
Authorization: YOUR_API_KEY
Accept: */*
{
"deleted_ids": [
"text"
]
}DELETE /api/v1/posts?post_ids=text HTTP/1.1
Host: app.publer.com
Authorization: YOUR_API_KEY
Publer-Workspace-Id: text
Accept: */*
[
{
"id": "63c675b54e299e9cf2b667ea",
"provider": "bluesky",
"name": "Tech News Daily",
"social_id": "at://did:plc:q6gjnaw2blty4crticxkmujt/app.bsky.feed.post/3kje3rifpm22n",
"picture": "https://publer-dev.s3.amazonaws.com/uploads/avatars/bluesky_profile.jpg",
"type": "profile"
}
]GET /api/v1/accounts HTTP/1.1
Host: app.publer.com
Authorization: YOUR_API_KEY
Publer-Workspace-Id: text
Accept: */*
[
{
"account_id": "text",
"signatures": [
{
"id": "text",
"label": "text",
"text": "text",
"default": true,
"in_photo_captions": true
}
]
}
]GET /api/v1/workspaces/{workspace_id}/signatures?accounts=text HTTP/1.1
Host: app.publer.com
Authorization: YOUR_API_KEY
Accept: */*
{
"id": "68176f0e8bee9dc9b0ce3427",
"text": "Check out our new product launch!",
"state": "scheduled",
"type": "photo",
"account_id": "63c675b54e299e9cf2b667ea",
"account": {
"id": "63c675b54e299e9cf2b667ea",
"type": "facebook_page",
"name": "My Business Page",
"picture": "https://graph.facebook.com/123456789/picture"
},
"user": {
"id": "5b1ec026db27977424e8599e",
"name": "ervintorra",
"picture": "https://publer-dev.s3.amazonaws.com/uploads/photos/thumb_mini_magick20250123-28707-otuw0w.png"
},
"scheduled_at": "2025-05-15T14:30:00.000+02:00",
"created_at": "2025-04-28T10:15:23.000+02:00",
"updated_at": "2025-04-29T11:30:45.000+02:00",
"post_link": "https://facebook.com/post/123456789",
"media": [
{
"id": "66fba4234e299e531f5dc100",
"type": "image",
"url": "https://publer-media.s3.amazonaws.com/uploads/images/product-launch.jpg",
"alt_text": "Product launch announcement image"
}
],
"link": {
"url": "https://example.com/product-launch",
"title": "New Product Launch",
"description": "Check out our latest product innovation",
"image_url": "https://example.com/images/product.jpg"
},
"labels": [
{
"id": "607c2f9a5e2c3d0789abcdef",
"name": "Product Launch",
"color": "#FF5733"
}
],
"auto": false,
"recycling": {
"solo": true,
"gap": 2,
"gap_freq": "Week",
"start_date": "2025-06-01",
"expire_count": 3
},
"recurring": {
"frequency": "Week",
"repeat_every": 1,
"weekdays": [
"Monday"
],
"start_date": "2025-06-02T09:00:00.000Z"
}
}PUT /api/v1/posts/{id} HTTP/1.1
Host: app.publer.com
Authorization: YOUR_API_KEY
Publer-Workspace-Id: text
Content-Type: application/json
Accept: */*
Content-Length: 39
{
"post": {
"text": "text",
"title": "text"
}
}[
{
"engagements": 1250,
"posts": 42,
"reach": 15000,
"account_ids": [
"63c675b54e299e9cf2b667ea",
"63c675b54e299e9cf2b667eb"
],
"user": {
"id": "5b1ec026db27977424e8599e",
"name": "John Smith",
"picture": "https://publer-dev.s3.amazonaws.com/uploads/photos/thumb_mini_magick20250123-28707-otuw0w.png"
}
}
]GET /api/v1/analytics/members?from=2025-12-10&to=2025-12-10 HTTP/1.1
Host: app.publer.com
Publer-Workspace-Id: text
Accept: */*
{
"media": [
{
"id": "5f5fe854421aa9792e762b70",
"type": "photo",
"name": "Beach sunset",
"caption": "Beautiful sunset at the beach",
"path": "https://cdn.publer.com/uploads/photos/5f5fe854421aa9792e762b70.jpg",
"thumbnails": [
{
"id": "5f6a1234421aa9792e762b71",
"small": "text",
"real": "text"
}
],
"created_at": "2023-05-15T10:30:00Z",
"updated_at": "2023-05-15T10:30:00Z",
"favorite": true,
"in_library": false
}
],
"total": 10
}GET /api/v1/media?types=photo&used=true HTTP/1.1
Host: app.publer.com
Authorization: YOUR_API_KEY
Publer-Workspace-Id: text
Accept: */*
[
{
"id": "text",
"name": "text",
"info": "Main office in New York City ⋅ 1,030 follow this",
"verified": true
}
][
{
"id": "text",
"name": "text",
"info": "Main office in New York City ⋅ 1,030 follow this",
"verified": true
}
][
{
"id": "text",
"name": "text",
"info": "Main office in New York City"
}
]GET /api/v1/locations/facebook?q=text HTTP/1.1
Host: app.publer.com
Accept: */*
GET /api/v1/locations/instagram?q=text HTTP/1.1
Host: app.publer.com
Accept: */*
GET /api/v1/locations/threads?q=text HTTP/1.1
Host: app.publer.com
Accept: */*
{
"Monday": [
0,
0,
0,
0,
0,
0,
5,
12,
18,
25,
22,
15,
8,
10,
16,
20,
18,
14,
12,
8,
5,
3,
1,
0
],
"Tuesday": [
0,
0,
0,
0,
0,
0,
6,
15,
20,
28,
25,
18,
10,
12,
18,
22,
20,
16,
14,
10,
6,
4,
2,
0
],
"Wednesday": [
0,
0,
0,
0,
0,
0,
7,
16,
22,
30,
27,
20,
12,
14,
20,
24,
22,
18,
16,
12,
8,
5,
3,
0
]
}GET /api/v1/analytics/{account_id}/best_times?from=2025-12-10&to=2025-12-10 HTTP/1.1
Host: app.publer.com
Publer-Workspace-Id: text
Accept: */*
[
{
"id": "followers",
"title": "Followers",
"group_id": "growth",
"tooltip": "text",
"type": "vertical",
"last_value": true,
"show_percentage": true
}
]{
"current": {
"ANY_ADDITIONAL_PROPERTY": {}
},
"previous": {
"ANY_ADDITIONAL_PROPERTY": {}
}
}GET /api/v1/analytics/charts HTTP/1.1
Host: app.publer.com
Publer-Workspace-Id: text
Accept: */*
GET /api/v1/analytics/chart_data?chart_ids=text HTTP/1.1
Host: app.publer.com
Publer-Workspace-Id: text
Accept: */*
[
{
"provider": "text",
"name": "text",
"social_id": "text",
"picture": "text",
"type": "text",
"competitor_sync_in_queue": true,
"username": "text",
"verified": true
}
]{
"insights": [
{
"account": {
"id": "text",
"name": "text",
"provider": "text",
"competitor_sync_in_queue": true,
"picture": "text",
"my_account": true
},
"followers": 1,
"followers_growth": 1,
"engagement": 1,
"engagement_rate": 1,
"reach": 1,
"posts_count": 1,
"videos_count": 1,
"photos_count": 1,
"links_count": 1,
"statuses_count": 1
}
],
"total": 1
}GET /api/v1/competitors/{account_id} HTTP/1.1
Host: app.publer.com
Publer-Workspace-Id: text
Accept: */*
GET /api/v1/competitors/{account_id}/analytics HTTP/1.1
Host: app.publer.com
Publer-Workspace-Id: text
Accept: */*
{
"link": {
"title": "text",
"description": "text",
"url": "text",
"original_url": "text",
"images": [
"text"
],
"favicon": "text",
"provider_display": "text",
"type": "link"
}
}POST /api/v1/posts/links HTTP/1.1
Host: app.publer.com
Authorization: YOUR_API_KEY
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 14
"url='text'"{
"id": "6813892b5ec8b1e65235ae9e",
"path": "https://cdn.publer.io/uploads/tmp/1746110763-128246820936684-0001-1648/mini_magick20250501-29172-ce1rot.png",
"thumbnail": "https://cdn.publer.io/uploads/tmp/1746110763-128246820936684-0001-1648/mini_magick20250501-29172-ce1rot.png",
"validity": {},
"width": 1451,
"height": 1005,
"source": null,
"type": "photo",
"name": "123_1kdw8ry.png",
"caption": null
}{
"job_id": "68138a295ec8b1e65235aea0"
}{
"success": true,
"data": {
"status": "complete",
"result": {
"status": "working",
"payload": {
"failures": {
"error": "Failed to upload media",
"code": 500
}
},
"plan": {
"rate": "business",
"locked": false
}
}
}
}POST /api/v1/media HTTP/1.1
Host: app.publer.com
Authorization: YOUR_API_KEY
Publer-Workspace-Id: text
Content-Type: multipart/form-data
Accept: */*
Content-Length: 56
{
"file": "text",
"direct_upload": false,
"in_library": false
}POST /api/v1/media/from-url HTTP/1.1
Host: app.publer.com
Authorization: YOUR_API_KEY
Publer-Workspace-Id: text
Content-Type: application/json
Accept: */*
Content-Length: 220
{
"media": [
{
"url": "https://example.com/path/to/image.jpg",
"name": "instagram: @auchynnikau",
"caption": "Photo by Slava Auchynnikau on Unsplash",
"source": "unsplash"
}
],
"type": "single",
"direct_upload": false,
"in_library": false
}GET /api/v1/job_status/{job_id} HTTP/1.1
Host: app.publer.com
Authorization: YOUR_API_KEY
Publer-Workspace-Id: text
Accept: */*
{
"success": true,
"data": {
"job_id": "6810dec617eae6d55d7a5e5b"
}
}{
"success": true,
"data": {
"job_id": "6810dec617eae6d55d7a5e5b"
}
}{
"success": true,
"data": {
"status": "complete",
"result": {
"status": "working",
"payload": {
"failures": {
"error": "Failed to upload media",
"code": 500
}
},
"plan": {
"rate": "business",
"locked": false
}
}
}
}POST /api/v1/posts/schedule HTTP/1.1
Host: app.publer.com
Authorization: YOUR_API_KEY
Publer-Workspace-Id: text
Content-Type: application/json
Accept: */*
Content-Length: 1029
{
"bulk": {
"state": "scheduled",
"posts": [
{
"networks": {
"facebook": {
"type": "status",
"text": "Check out our new product launch!"
}
},
"accounts": [
{
"id": "63c675b54e299e9cf2b667ea",
"scheduled_at": "2025-05-17T16:19+02:00",
"labels": [],
"previewed_media": true,
"share": {
"text": "text",
"account_ids": [
"text"
],
"after": {
"duration": 1,
"unit": "Minute"
},
"delay": {
"duration": 1,
"unit": "Minute"
}
},
"comments": [
{
"text": "text",
"language": "text",
"delay": {
"duration": 1,
"unit": "Minute"
},
"media": {
"type": "photo",
"path": "text",
"caption": "text",
"thumbnail": "text",
"thumbnails": {
"real": "text",
"small": "text"
}
}
}
],
"delete": {
"hide": true,
"delay": {
"duration": 1,
"unit": "Minute"
}
}
}
],
"recycling": {
"solo": true,
"gap": 2,
"gap_freq": "Week",
"start_date": "2025-05-24",
"expire_count": "1",
"expire_date": "2025-06-14"
},
"recurring": {
"start_date": "2025-05-05T13:29+02:00",
"end_date": "2025-06-21T13:29+02:00",
"repeat": "weekly",
"days_of_week": [
1,
4,
6
],
"repeat_rate": 1
},
"share_next": false,
"range": {
"start_date": "2025-05-31T08:43:00.000Z",
"end_date": "2025-06-08T08:43:00.000Z"
},
"auto": true
}
]
}
}POST /api/v1/posts/schedule/publish HTTP/1.1
Host: app.publer.com
Authorization: YOUR_API_KEY
Publer-Workspace-Id: text
Content-Type: application/json
Accept: */*
Content-Length: 1029
{
"bulk": {
"state": "scheduled",
"posts": [
{
"networks": {
"facebook": {
"type": "status",
"text": "Check out our new product launch!"
}
},
"accounts": [
{
"id": "63c675b54e299e9cf2b667ea",
"scheduled_at": "2025-05-17T16:19+02:00",
"labels": [],
"previewed_media": true,
"share": {
"text": "text",
"account_ids": [
"text"
],
"after": {
"duration": 1,
"unit": "Minute"
},
"delay": {
"duration": 1,
"unit": "Minute"
}
},
"comments": [
{
"text": "text",
"language": "text",
"delay": {
"duration": 1,
"unit": "Minute"
},
"media": {
"type": "photo",
"path": "text",
"caption": "text",
"thumbnail": "text",
"thumbnails": {
"real": "text",
"small": "text"
}
}
}
],
"delete": {
"hide": true,
"delay": {
"duration": 1,
"unit": "Minute"
}
}
}
],
"recycling": {
"solo": true,
"gap": 2,
"gap_freq": "Week",
"start_date": "2025-05-24",
"expire_count": "1",
"expire_date": "2025-06-14"
},
"recurring": {
"start_date": "2025-05-05T13:29+02:00",
"end_date": "2025-06-21T13:29+02:00",
"repeat": "weekly",
"days_of_week": [
1,
4,
6
],
"repeat_rate": 1
},
"share_next": false,
"range": {
"start_date": "2025-05-31T08:43:00.000Z",
"end_date": "2025-06-08T08:43:00.000Z"
},
"auto": true
}
]
}
}GET /api/v1/job_status/{job_id} HTTP/1.1
Host: app.publer.com
Authorization: YOUR_API_KEY
Publer-Workspace-Id: text
Accept: */*
{
"posts": [
{
"id": "text",
"text": "text",
"title": "text",
"scheduled_at": "2025-12-10T00:33:44.342Z",
"post_type": "text",
"account_id": "text",
"details": {
"labels": [
{
"id": "text",
"name": "text",
"color": "text"
}
]
},
"analytics": {
"reach": 1,
"engagement": 1,
"engagement_rate": 1,
"likes": 1,
"comments": 1,
"shares": 1,
"saves": 1,
"video_views": 1,
"link_clicks": 1,
"post_clicks": 1,
"click_through_rate": 1,
"reach_rate": 1
}
}
],
"total": 1
}GET /api/v1/analytics/{account_id}/post_insights?from=2025-12-10&to=2025-12-10 HTTP/1.1
Host: app.publer.com
Publer-Workspace-Id: text
Accept: */*
{
"posts": [
{
"id": "68176f0e8bee9dc9b0ce3427",
"text": "Check out our new product launch!",
"url": "https://example.com/product-launch",
"state": "scheduled",
"type": "status",
"account_id": "63c675b54e299e9cf2b667ea",
"user": {
"id": "5b1ec026db27977424e8599e",
"name": "ervintorra",
"picture": "https://publer-dev.s3.amazonaws.com/uploads/photos/thumb_mini_magick20250123-28707-otuw0w.png"
},
"scheduled_at": "2025-05-15T14:30:00.000+02:00",
"post_link": "https://facebook.com/post/123456789",
"has_media": true,
"network": "facebook"
}
],
"total": 42,
"page": 1,
"per_page": 20,
"total_pages": 3
}GET /api/v1/posts HTTP/1.1
Host: app.publer.com
Authorization: YOUR_API_KEY
Publer-Workspace-Id: text
Accept: */*
{
"records": [
{
"hashtag": "socialmedia",
"posts": 1,
"recent_posts": [
{
"id": "text",
"text": "text",
"scheduled_at": "2025-12-10T00:33:44.342Z"
}
],
"reach": 1,
"likes": 1,
"comments": 1,
"shares": 1,
"engagement": 1,
"video_views": 1,
"link_clicks": 1,
"post_clicks": 1,
"saves": 1,
"hashtag_score": 1
}
],
"total": 1
}[
{
"id": "text",
"text": "text",
"title": "text",
"scheduled_at": "2025-12-10T00:33:44.342Z",
"account_id": "text",
"hashtags": [
"text"
],
"analytics": {
"reach": 1,
"likes": 1,
"comments": 1,
"shares": 1,
"engagement": 1,
"engagement_rate": 1,
"video_views": 1,
"link_clicks": 1,
"post_clicks": 1,
"saves": 1
},
"details": {
"labels": [
{
"id": "text",
"name": "text"
}
]
}
}
]GET /api/v1/analytics/{account_id}/hashtag_insights HTTP/1.1
Host: app.publer.com
Publer-Workspace-Id: text
Accept: */*
GET /api/v1/analytics/{account_id}/hashtag_performing_posts?hashtag=text HTTP/1.1
Host: app.publer.com
Publer-Workspace-Id: text
Accept: */*