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

• Analytics:

  • Charts: Discover available analytics charts and fetch chart data for dashboards

  • Post Insights: Per‑post metrics with filtering, sorting, pagination, and competitor mode

• Build custom integrations, dashboards, or bots

API Specifications

Authentication

Include your API token in every request header:

Authorization: Bearer-API YOUR_API_TOKEN
Publer-Workspace-Id: YOUR_WORKSPACE_ID // Required on special cases
Content-Type: application/json

Manage and regenerate tokens in Settings → Access & Login → API Keys.

Getting Started

1. Generate an API key in your Publer Dashboard.

2. Validate your credentials:

   Copy

   curl -H "Authorization: Bearer YOUR_API_TOKEN" \
        https://app.publer.com/api/v1/me

3. Follow our quickstart guide to make your first API request

4. Explore the full for detailed endpoint docs.

Support & Resources

If you need assistance with the API:

• Review our quickstart guide for basic concepts

• Check the API reference for detailed endpoint information

• Contact support@publer.com for technical issues

Jump right in

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

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

2. Navigate to .

3. Click Create API Key.

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.

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

GET /api/v1/users/me

Related Resources

• Authentication - Managing API keys and scopes

• Workspaces API - Access workspace information

• Rate Limits - Understanding API usage limits

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.

GET /api/v1/workspaces

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:

curl -X GET https://app.publer.com/api/v1/accounts \
  -H "Authorization: Bearer-API YOUR_API_KEY" \
  -H "Publer-Workspace-Id: 61a7c2e4f9e8c3b2d1e0f9a8"

Related Resources

• Users API - Access user profile information

• Accounts API - Access social accounts within workspaces

• Posts API — Create, schedule, and manage content

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

• Authentication: Bearer API token

• Scope: accounts

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

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

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

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

Endpoint

POST /api/v1/posts/schedule/publish

Request Headers

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.

• - Details on different content formats

• - Information about uploading and managing media

• - Platform-specific capabilities and limitations

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

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

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.

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

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 Requesting Higher Limits 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

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

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:

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:

• Dated drafts: drafts with a set date/time (these typically show up in Calendar views in the UI).

• Undated drafts: drafts without a set date/time (stored under Drafts in the UI for later review/scheduling).

Draft Posts are created via the scheduling endpoint using:

• bulk.state = "draft"

Draft Posts support the same post structures as normal scheduled/published posts, meaning you can create different kinds of drafts (photos, videos, carousels, reels, etc.) depending on the provider.

Use the scheduling endpoint with bulk.state: "draft" to save work-in-progress content without publishing.

Drafts connected to specific social accounts that can optionally include scheduling information.

Key Features

• Must include accounts array with account IDs

• Can include scheduled_at for future publishing (dated drafts)

• Uses specific network keys (e.g., facebook

Example Request

• For Draft Posts (bulk.state = "draft"), use specific provider keys inside posts[].networks (e.g. facebook, instagram, twitter, etc.).

• The network payload structure depends on the provider and content type (e.g., status, photo, video, carousel, story, reel, etc.).

Draft Posts can be created using any supported content type (the type field inside networks.[provider]).

See the full reference.

• Save often: create drafts early to avoid losing work-in-progress content.

• Use dated drafts as reminders: set scheduled_at to place drafts on a timeline for later review/publishing.

• Use the right tool: Draft Posts are for content already tied to specific social accounts. (Use for account-less planning and templates.)

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

POST /api/v1/posts/schedule

Request Headers

Set auto: true and define range to enable auto-scheduling:

Omit end_date and set share_next to schedule at the next open slot:

1. Analyze Schedule: Publer looks at your existing posting queue and calendar.

2. Identify Slots: Finds open time slots based on your account’s posting schedule.

3. Optimize: Uses audience engagement data to pick a high-impact time within your range.

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

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

Visual content that drives engagement across social networks. Use photo posts to share high-quality images—single or multiple—while respecting each platform’s unique requirements.

Key Features

• Multi-Platform Publishing Post images simultaneously to all supported networks.

• Multiple Image Support Single photos or carousels (up to platform limits).

• Advanced Customization Captions and location tags where available.

• Resolution Optimization Automatic resizing and format handling per network.

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.

* Omit scheduled_at when publishing immediately.

1. Upload Images: Use the to upload files.

2. Receive IDs: Note each media object’s id.

3. Compose Post: Reference those IDs in your media array.

• Optimize Quality: Compress and resize images to platform specs.

• Descriptive Alt Text: Enhance accessibility and SEO.

• Tailor Captions: Adjust tone and length per network.

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.

• You can only post to Communities you have joined.

• Community posts help foster deeper engagement on niche topics or interests.

How It Works

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:

1. Go to the Community on X.

2. Look at the URL: https://x.com/i/communities/1492410432069451776

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

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

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

Requirements

• Authentication: Bearer API token

• Scope: posts

• Headers:

  • Authorization: Bearer-API YOUR_API_KEY

  • Publer-Workspace-Id: YOUR_WORKSPACE_ID

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)

• Pinterest

• Instagram

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

Requirements

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

• — Discover chart IDs and fetch chart data

• — Per‑post performance analytics

• — Hashtag performance

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.

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

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

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)

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.

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.

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:

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

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.

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.

Authentication: Bearer API token Scope: analytics Headers:

• Authorization: Bearer-API YOUR_API_KEY

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: