Introduction

Welcome to the Publer API. This RESTful JSON API brings Publer’s social media scheduling, publishing, and analytics capabilities into your own applications, scripts, or services. Whether you’re automating campaigns, building dashboards, or integrating content workflows, the Publer API provides the same power you know from the Publer web platform.

What is Publer?

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.

What can I do with the Publer API?

• 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

API Specifications

Authentication

Include your API token in every request header:

Manage and regenerate tokens in .

Getting Started

1. Generate an API key in your Publer Dashboard.

2. Validate your credentials:

3. Follow our to make your first API request

Support & Resources

If you need assistance with the API:

• Review our for basic concepts

• Check the for detailed endpoint information

• Contact for technical issues

Jump right in

Manage organizational units (“workspaces”) that group social accounts, members, and content. Workspaces help agencies, brands, and departments keep clients and campaigns separate under a single Publer login.

Requirements

• Authentication: Bearer API token

• Scope: workspaces

• Headers:

  • Authorization: Bearer-API YOUR_API_KEY

Endpoint

List Workspaces

Retrieve all workspaces accessible by the authenticated user.

Working with Workspaces

• A user can belong to multiple workspaces.

• Each workspace has its own accounts, posts, and settings.

• Use the workspace context (Publer-Workspace-Id header) to target API calls at the correct workspace.

Workspace Context for Other Endpoints

Many endpoints require you to specify which workspace you’re operating in. Include the Publer-Workspace-Id header:

Related Resources

• - Access user profile information

• - Access social accounts within workspaces

• — Create, schedule, and manage content

Retrieve profile and application settings for the currently authenticated user. Use this endpoint to adapt your integration to user preferences and entitlements.

Requirements

• Authentication: Bearer API token

• Headers:

  • Authorization: Bearer-API YOUR_API_KEY

Endpoint

Get Current User

Related Resources

• - Managing API keys and scopes

• - Access workspace information

• - Understanding API usage limits

The Media API lets you list and filter items in your library. You can page through results, query by IDs, or apply filters such as type, usage status, source, and search terms.

Requirements

• Authentication: Bearer API token

• Scope: media

• Headers:

  • Authorization: Bearer-API YOUR_API_KEY

  • Publer-Workspace-Id: YOUR_WORKSPACE_ID

Endpoint

List Media

Retrieve all social media accounts in a workspace.

Query Parameters

Notes

• Free trial users see placeholder data unless they supply specific query filters.

• Paid accounts have full library access.

Related Resources

• — Manage connected social accounts

• — Create and schedule posts

• — Upload new media files

What Is the Publer API?

A RESTful JSON interface for automating social media workflows—scheduling, publishing, media management, and analytics—across multiple networks.

Base URL

Manage and retrieve social media accounts connected to your Publer workspaces. Use these accounts as targets when scheduling or publishing content.

Requirements

• Authentication: Bearer API token

Every Publer API request must include a valid API key. This guide shows you how to obtain, use, and manage your keys securely.

Obtaining an API Key

1. Sign in to your Publer account (Business plan).

To keep our service reliable and fair, the Publer API enforces rate limits on all requests. Limits are applied per user account (across all API keys) and use a fixed-window algorithm.

Default Limits

Note: If you need higher throughput for your integration, see below.

Tracking Your Usage

When you reach the rate limits, every API response includes these headers so you can monitor your rate limit status:

Example Response Headers

When You Exceed the Limit

If you go over your quota, the API returns:

• HTTP Status: 429 Too Many Requests

• Response Body:

• Headers will show X-RateLimit-Remaining: 0 and a future X-RateLimit-Reset.

Daily Post Limits

While most social networks don't explicitly limit daily posts, Publer implements posting limits to prevent spam, ensure compliance with platform guidelines, and allocate resources fairly. These limits are calculated on a rolling 24-hour basis in UTC timezone.

Post Limits by Plan

Important Notes

• Rolling 24-hour window: Limits are calculated based on the previous 24 hours from the current time (UTC)

• Per profile/account: Facebook limits apply per connected profile or page

• Anti-spam protection: These limits help maintain a balance between automation and spam prevention

Best Practices to Avoid Throttling

• Cache responses for idempotent or infrequently changing endpoints.

• Use bulk endpoints (e.g., POST /api/v1/posts/schedule for multiple posts).

• Stagger non-urgent requests during off-peak hours.

Requesting Higher Limits

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:

Each social network offers unique post formats. Publer’s API supports these specialized types—click a format to dive into its implementation details:

• Text Posts with Background

• Multi-Link Posts (Facebook Carousels)

• Polls

Best Practices

• 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.

Related Topics

This guide walks you through the core steps to integrate with Publer’s API in minutes. By the end, you’ll have published your first scheduled post.

Prerequisites

• A Business Publer account

A comprehensive overview of all content formats you can publish via the Publer API. Each content type is specified by the type field inside the networks.[provider] object.

Supported Content Types

Remove one or multiple posts—of any state—from your workspace. This endpoint enforces role-based permissions and state-specific restrictions.

Requirements

• Authentication: Bearer API token

Unlock the ability to schedule and publish long-form posts (up to 25,000 characters) to Twitter/X using the Publer API—exclusively for accounts with an X Premium subscription.

Overview

Twitter/X supports long-form posts (sometimes called "long posts" or "extended tweets") for users with an X Premium (formerly Twitter Blue) subscription, even at the Basic tier. These posts can contain up to 25,000 characters, far exceeding the standard 280-character limit.

With Publer, you can programmatically schedule and publish long-form posts via the API. Publer automatically detects your account’s eligibility and switches to the appropriate post type.

How It Works

• Accounts with X Premium: You can create and schedule long-form posts up to 25,000 characters.

• Accounts without X Premium: Your post text will be truncated to the standard 280-character limit, and the long-form post type will be disabled.

Tip: Validate the post length in your integration to avoid surprises when publishing.

Key Differences

• Long-form posts are not the same as Twitter threads. Threads are multiple connected posts; long-form posts are a single post with expanded character count.

• Scheduling long-form posts is not possible directly on X/Twitter—use Publer’s API or platform to achieve this functionality.

Request Example

To schedule a Twitter/X long-form post, set the network type to "long_post" inside the details object for the "twitter" network:

Important Notes

• X Premium Required: Only X Premium accounts can publish long-form posts. For other accounts, posts will be truncated to 280 characters.

• Not for Threads: Use this format for single extended posts, not for multi-part threads.

• API Detection: Publer automatically detects account eligibility for long-form posting.

Best Practices

• Check your account’s X Premium status before relying on long-form functionality.

• Always validate post length to ensure your content is not unintentionally truncated.

• Use long-form posts for in-depth announcements, articles, or detailed updates—threads remain better for sequential storytelling.

Related Topics

The Members endpoint returns posting activity and engagement metrics per workspace member, optionally scoped to a single account and time range. Use it to build leaderboards, performance reviews, and workload reports.

Requirements

Authentication: Bearer API token Scope: analytics Headers:

• Authorization: Bearer-API YOUR_API_KEY

• Publer-Workspace-Id: YOUR_WORKSPACE_ID

Endpoint

Get Members Analytics

Description

Retrieves analytics for each workspace member within a required date range. Optionally filter to a specific social account.

Query Parameters

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).

Notes

• Date range is required; ensure from ≤ to.

• If account_id is omitted, metrics aggregate across all accessible accounts in the workspace.

• reach

Related Resources

• — Discover chart IDs and fetch chart data

• — Per‑post performance analytics

• — Hashtag performance

The Posts Create endpoints let you asynchronously schedule, draft, or immediately publish content across one or more social networks. Submit a batch request, receive a job ID, then poll for completion.

Requirements

• Authentication: Bearer API token

The Posts API lets you list, filter, and inspect social media posts across your connected accounts. Build dashboards, content calendars, or analytics by combining powerful query parameters.

Requirements

• Authentication: Bearer API token

Publish content to social networks instantly using the Publer API. This method skips scheduling and sends posts for immediate delivery.

Endpoint

Request Headers

Schedule posts for future publication across one or more social networks using the Publer API.

Endpoint

Request Headers

The Best Times to Post endpoint returns a heatmap of optimal posting times for a specific account, based on historical performance. Use it to power schedule suggestions, calendar overlays, and autofill routines.

Requirements

Authentication: Bearer API token Scope: analytics Headers:

Publish posts directly to Twitter/X Communities using the Publer API. This feature enables you to reach targeted audiences and participate in focused discussions within X Communities—right from your own app or workflow.

Overview

Twitter/X Communities are spaces for people to connect, share, and discuss specific topics. Posts made in a Community are visible to anyone on X, but only Community members can engage (like, reply, etc.) with them.

Modify an existing post—whether scheduled or already published—across your social networks. This endpoint handles network-specific constraints and supports advanced features like recycling and recurring schedules.

Requirements

• Authentication: Bearer API token

Automatically append a branded or informative signature to your social posts. Signatures help drive consistency and professionalism across your accounts.

Overview

A signature is a reusable block of text (such as a disclaimer, call-to-action, or branded tagline) you can attach to posts on supported networks. You can manage multiple signatures per account and select which one to append when scheduling or publishing.

Tag your posts with a real-world location to increase engagement and reach more local audiences. Publer supports location tagging for Facebook Pages, Instagram Business accounts and Threads accounts.

Overview

Location tagging attaches a physical place (such as a city, office, or venue) to your Facebook, Instagram or Threads post. This is especially helpful for businesses, events, and local marketing.

Step 1: Search for a Location

Use Publer’s dedicated endpoints to search and select the correct location for your post:

Location Object Example:

Step 2: Schedule or Publish a Post with a Location

When creating or scheduling a post, use the location object inside the relevant accounts array:

Example Request:

Parameters

Key Notes & Limitations

• 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.

Best Practices

• 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

Related Topics

Animated GIFs are a fun, engaging way to capture attention. Use the Publer API to create or schedule single‐GIF posts with caption and thumbnail support across multiple platforms.

Overview

GIF posts let you share looping animations with optional captions and metadata. Perfect for reactions, announcements, or adding personality to your feed.

Key Features

• Cross-Platform GIF Publishing

• Custom Caption Support

• Thumbnail Preview

• Immediate or Scheduled Posting

Platform Support & Limits

Request Structure

Send to the scheduling endpoint (/posts/schedule) or immediate‐publish (/posts/schedule/publish):

Required Parameters

Workflow

1. Reference or upload your GIF via the .

2. Build your post object with "type": "gif".

3. (Optional) Add "thumbnail" and "name" for preview.

Best Practices

• Compress GIFs to meet platform size limits without sacrificing quality.

• Provide a clear, engaging thumbnail to boost click-through.

• Use concise captions to add context or calls-to-action.

Related Topics

Manage and retrieve Facebook albums, Pinterest boards, and saved watermarks for your social accounts—all within your workspace. Use these options to organize content and protect your creative assets.

Overview

Media options help you:

• Post 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.

Fetch Media Options

Use the following endpoint to list all available albums (for Facebook), boards (for Pinterest), and saved watermarks for the accounts in your workspace.

Parameters

How to Use Media Options

• Facebook Albums: Select an album ID when posting to Facebook to keep your photos organized and easy to browse.

• Pinterest Boards: Use the board ID to specify where your Pin should be published.

• Watermarks: Choose a watermark ID to apply a logo, copyright, or brand mark to your images/videos. Watermarks help deter unauthorized use and reinforce your brand.

Related Topics

Create, manage, and collaborate on draft posts that aren't published immediately. Drafts help you save work-in-progress content, collaborate with your team, and schedule posts for later publishing.

Overview

Draft posts are unfinished posts connected to a social account. They can be:

Automatically pick the optimal posting time for your content within a specified date window. Publer analyzes your posting schedule and audience engagement to fill gaps and maximize reach.

Endpoint

Request Headers

Protect your creative content and reinforce your brand by automatically applying watermarks to photos and videos you share across your social accounts.

Overview

A watermark is a logo or symbol placed on your media to discourage unauthorized use and promote your brand. With Publer, you can save, manage, and apply unique watermarks per account—no editing skills required.

Watermarking is available on the Professional Plan for images and the Business Plan for videos.

Create and schedule multi‐link carousel posts on Facebook Pages. Carousels let you showcase up to 10 clickable cards—each with its own image, title, description, and call-to-action—in a single organic post.

Request Body

Parameters

Simple yet powerful status updates without media attachments. Text posts are widely supported, versatile, and often drive high engagement.

Overview

Text posts (status updates) let you share plain-text messages across all major social networks. With the Publer API you can:

• Publish or schedule text updates simultaneously to multiple platforms