Only this pageAll pages
Powered by GitBook
1 of 55

Publer API

Loading...

Getting Started

Loading...

Loading...

Loading...

API REFERENCE

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Posting

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

Analytics

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Quickstart Guide

BUSINESS ACCESS ONLY: The Publer API is currently available exclusively to Publer Business users.

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

Prerequisites

  • A Business Publer account

  • Basic familiarity with HTTP/JSON APIs

  • A command-line tool (curl) or API client (Postman, Insomnia)

Step 1: Generate an API Key

  1. Sign in to Publer and verify you have Business plan access.

  2. Go to Settings → Access & Login → API Keys.

  3. Click Create API Key.

  4. Enter a descriptive name, then select scopes:

Step 2: List Workspaces

Before making other requests, let's retrieve your workspaces. The workspace ID is required in the header for most API operations:

Sample Response

Now you can use a workspace ID in your subsequent requests by including it in the header:

Step 3: List Social Accounts

Next, let's retrieve the social media accounts in your workspace. You'll need the account IDs to specify where to publish your posts:

Expected Response

Make note of the account IDs as you'll need them to specify where to publish your content in the next step.

Step 4: Create a Scheduled Post

Make your first scheduled post with one API call:

Sample Response

The API returns a job ID that you can use to check the status of your request:

Step 5: Poll Job Status

Posts are created asynchronously. Use the returned job_id to check progress:

Successful Job Response

Failed Job Response

If there's an error with your request, the response will include details about what went wrong:

Step 6: Verify Scheduled Posts

List your scheduled posts to confirm creation:

Sample Response

Understanding the Workflow

  1. Generate an API key

  2. List workspaces → pick a workspace ID

  3. List accounts → pick account IDs

  4. Submit a post creation request

This async pattern scales across multiple workspaces, accounts, and post types.

Next Steps

  • Explore (photos, videos, links, polls)

  • Dive into and upload workflows

  • Learn about (drafts, recurring posts)

  • Review for platform-specific limits

For full API details, see the . For assistance, contact .

Overview

Access & Availability The Publer API is available exclusively to Business and Enterprise customers. Upgrade your plan

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

Property
Value

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

  4. Explore the full for detailed endpoint docs.

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

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

  • Content Types
    Media Handling
    Publishing Methods
    Network Reference
    API Reference
    [email protected]

    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

    Settings → Access & Login → API Keys
    quickstart guide
    API reference
    quickstart guide
    API reference
    [email protected]

    Quickstart

    Get up and running with the API in minutes

    Authentication

    Learn how to authenticate your API requests

    API Reference

    Explore detailed endpoint documentation

    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: 5f8d7a62c9e77e001f36e3a1
    curl -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/json
    curl -H "Authorization: Bearer YOUR_API_TOKEN" \
         https://app.publer.com/api/v1/me

    Users

    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

    Platform-Specific Formats

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

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

    • Test & Iterate Experiment across formats to discover what resonates best with your audience.

    Related Topics

    Workspaces

    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

    LinkedIn PDF Carousels
    Pinterest Pins with a Link URL
    Google Events, Offers, and Photos
    Reels, Shorts, or Stories
    Media Handling
    Publishing Methods
    Content Types
    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

    • Users API - Access user profile information

    • Accounts API - Access social accounts within workspaces

    • Posts API — Create, schedule, and manage content

    Authentication
    Workspaces API
    Rate Limits

    Introduction

    BUSINESS ACCESS ONLY: The Publer API is currently available exclusively to Publer Business users.

    What Is the Publer API?

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

    Base URL

    All endpoints share this root URL:

    Authentication

    Include your API key and workspace ID on almost every request:

    Request Format

    GET

    Use query parameters for filters and pagination:

    POST, PUT, PATCH

    Send JSON in the request body:

    DELETE

    No request body is required (unless otherwise noted):

    Response Format

    All responses are JSON.

    Success

    • Synchronous endpoints return the requested resource or collection.

    • Asynchronous endpoints (e.g., post creation) return a job_id:

    Error

    • Status codes indicate general error type (4xx, 5xx).

    • The response body contains an errors array:

    Common HTTP Status Codes

    • 200 OK

    • 201 Created

    • 202 Accepted (async)

    • 400 Bad Request

    Versioning

    Current version: v1 (in the URL path). We follow . Breaking changes only occur on MAJOR version bumps; you will be notified in advance.

    Asynchronous Operations

    1. Submit your request → 202 Accepted + {"job_id": "…"}

    2. Poll the job status endpoint until complete:

    Date & Time

    All timestamps use ISO 8601 with timezone:

    Example: 2025-05-04T14:58:35+00:00

    Privacy & Security

    • Always use HTTPS.

    • Sensitive fields may be redacted.

    • Adhere to least-privilege scope selection.

    Next Steps

    For implementation examples, see the Quickstart Guide and sections on creating content, media handling, and network-specific formats.

    Media Options

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

    Overview

    Media options help you:

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

    Field
    Type
    Description

    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

    Deleting Posts

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

    Requirements

    • Authentication: Bearer API token

    • Scope: posts

    • Headers:

      • Authorization: Bearer-API YOUR_API_KEY

      • Publer-Workspace-Id: YOUR_WORKSPACE_ID

    Endpoint

    Deletes one or more posts based on the provided IDs.

    Query Parameters

    Authorization Rules

    • You may delete:

      • Posts you created

      • Posts in workspaces you own

      • Posts in workspaces where you have “post action” access

    Pending-state deletions trigger a notification to the creator before removal.

    Related Resources

    • - Retrieve and filter posts

    • - Modify existing posts

    Accounts

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

    Requirements

    • Authentication: Bearer API token

    GET /api/v1/workspaces
    curl -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/me
    401 Unauthorized
  • 403 Forbidden

  • 404 Not Found

  • 429 Too Many Requests

  • 500 Internal Server Error

  • Semantic Versioning
    Users API
    Workspaces API
    Accounts API
    Posts API
    https://app.publer.com/api/v1/
    Authorization: Bearer-API YOUR_API_KEY
    Publer-Workspace-Id: YOUR_WORKSPACE_ID
    Content-Type: application/json
    GET /posts?state=scheduled&from=2025-04-20
    POST /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:mm

    albums[].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

    Content Types
    Publishing Methods
    Media Handling

    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

    List Posts API
    Update Posts API
    Scope: accounts
  • Headers:

    • Authorization: Bearer-API YOUR_API_KEY

    • Publer-Workspace-Id: YOUR_WORKSPACE_ID

  • Endpoint

    List Accounts

    Retrieve all social media accounts in a workspace.

    Retrieves a list of all social media accounts available in the specified workspace.

    The list of accounts returned will include all social media accounts that you have connected to your Publer workspaces and have permission to access. These accounts can be used to schedule and publish content via the Posts API.

    The accounts data provides important information about the social media profiles available for posting, including their configuration settings and current synchronization status.

    Supported Providers

    Publer supports these network providers and account types:

    Provider

    Description

    Supported Account Types

    facebook

    Facebook

    page, group, profile

    instagram

    Instagram

    business

    twitter

    Twitter/X

    profile

    linkedin

    LinkedIn

    page, profile

    Related Resources

    • Workspaces API - Manage organizational units

    • Posts API - Create and publish content to accounts

    • Media API - Upload media files for posting

    Authentication

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

    Obtaining an API Key

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

    2. Navigate to .

    3. Click Create API Key.

    4. Enter a descriptive name for your key.

    5. Select only the scopes your integration needs (e.g., posts, media, accounts).

    6. Click Create.

    7. Copy and securely store the key — you won’t see it again.

    Using Your API Key

    Include your key in the Authorization header for every request. Also provide your workspace ID:

    Example (list posts):

    API Key Scopes

    When creating an API key, you must select specific permission scopes based on your integration needs:

    Common Authentication Errors

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

    Security Best Practices

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

    Troubleshooting

    If you continue to see authentication errors:

    1. Confirm your key is active and not expired.

    2. Verify you have the correct header names and values.

    3. Double-check that your key has the required scopes.

    4. Contact for assistance.

    Related Documentation

    Post with Signature

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

    Overview

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

    Step 1: Fetch Available Signatures

    Before attaching a signature to your post, retrieve the available signatures for your account(s):

    Step 2: Create or Schedule a Post with a Signature

    When scheduling or publishing a post, use the signature parameter within the relevant accounts object to append a signature to the post.

    Example Request:

    Parameters

    Field
    Type
    Description

    Key Notes & Limitations

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

    Best Practices

    • Craft signatures that reinforce your brand identity.

    • Use signatures for legal disclaimers, campaign CTAs, or promotional blurbs.

    • Set a default signature for frequent use.

    Related Topics

    GIF Posts

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

    Overview

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

    Key Features

    • Cross-Platform GIF Publishing

    • Custom Caption Support

    • Thumbnail Preview

    • Immediate or Scheduled Posting

    Platform Support & Limits

    Network
    Size Limit
    Notes

    Request Structure

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

    Required Parameters

    Field
    Description

    Workflow

    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

    Twitter/X Long-Form Posts

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

    Overview

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

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

    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:

    Field
    Type
    Description

    Important Notes

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

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

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

    • Scheduling Limitation: Twitter/X doesn’t natively support scheduling long-form posts; this is enabled via Publer’s platform and API.

    Best Practices

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

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

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

    Related Topics

    Manual Scheduling

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

    Endpoint

    Request Headers

    Header
    Required
    Description

    Request Body

    Include a valid ISO 8601 scheduled_at timestamp under each account:

    Sample Request

    Sample Response

    Status: 200 OK

    Key Fields

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

    Important Considerations

    Time Formats

    • Use full ISO 8601 format, including timezone (e.g., 2025-06-01T09:00:00+02:00).

    • Timestamps must be at least 1 minute in the future.

    Best Practices

    • Buffer Time: Space posts 1–2 minutes apart to avoid collisions.

    • Timezone Awareness: Schedule using your audience’s local time.

    • Batch Scheduling: Combine related posts in a single request for efficiency.

    • Verify: Poll /api/v1/job_status/{job_id}

    Related Topics

    • - Details on different content formats

    • - Advanced AI-based scheduling options

    • - Setting up repeating content

    • - Platform-specific scheduling limitations

    Updating Posts

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

    Requirements

    • Authentication: Bearer API token

    • Scope: posts

    • Headers:

      • Authorization: Bearer-API YOUR_API_KEY

      • Publer-Workspace-Id: YOUR_WORKSPACE_ID

    Endpoint

    Updates an existing post by ID. The behavior differs depending on whether the post is scheduled or already published.

    Parameter Reference

    Special Cases

    When the post is published, you can only update network-specific params.

    Networks Not Supporting Published Post Updates

    For the following networks, only labels can be updated in Publer's database after a post is published:

    • Twitter/X (polls cannot be edited after publishing)

    • Pinterest

    • Instagram

    • Threads

    Recurring Posts

    If the post is a recurring post, the update will be applied to all future child posts in the recurring series. Already published child posts will not be affected.

    Notes

    • When updating a post that requires approval, a notification will be sent to the appropriate workspace members.

    • Changes to published posts will be reflected both in Publer's database and on the social media platform (for supported networks).

    Related Resources

    • - Retrieve and filter posts

    • - Manage social media accounts

    • - Upload and manage media for posts

    Members

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

    Requirements

    Authentication: Bearer API token Scope: 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

    Param
    Type
    Required
    Description

    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 may be missing for networks that don’t expose member-level reach. Handle absent fields gracefully.

    Related Resources

    • — Discover chart IDs and fetch chart data

    • — Per‑post performance analytics

    • — Hashtag performance

    • — Suggested posting time slots

    Media

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

    Requirements

    • Authentication: Bearer API token

    • Scope: media

    • Headers:

      • Authorization: Bearer-API YOUR_API_KEY

      • Publer-Workspace-Id: YOUR_WORKSPACE_ID

    Endpoint

    List Media

    Retrieve all social media accounts in a workspace.

    Query Parameters

    Parameter
    Type
    Required
    Description

    Notes

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

    • Paid accounts have full library access.

    Related Resources

    • — Manage connected social accounts

    • — Create and schedule posts

    • — Upload new media files

    Post with Watermark

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

    Overview

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

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

    Post with Location

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

    Overview

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

    Best Times to Post

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

    Requirements

    Authentication: Bearer API token Scope: analytics Headers:

    DELETE /api/v1/posts
    GET /api/v1/accounts
    POST /api/v1/posts/schedule
    Least Privilege Create separate keys for different use cases.
  • Safe 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

    Settings → Access & Login → API Keys
    [email protected]
    Quickstart Guide
    Rate Limits
    API Reference

    Mastodon

    8 MB

    Supports JPEG, PNG, WEBP, and GIF

    Pinterest

    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)

    Call /posts/schedule or /posts/schedule/publish.
  • Monitor /api/v1/job_status/{job_id} for completion.

  • Facebook

    4 MB

    —

    Twitter/X

    15 MB

    4×4 to 2048×2048 px resolution

    LinkedIn

    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

    Media Handling API
    Platform-Specific Formats
    Publishing Methods
    Content Types

    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)

    Content Types Overview
    Publishing Methods
    linkedin
    ).
    to confirm scheduling success.

    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)

    Content Types
    Auto-Scheduling
    Recurring Posts
    Network Reference
    console.log(`Using key ***${apiKey.slice(-4)}`);
    Authorization: Bearer-API YOUR_API_KEY  
    Publer-Workspace-Id: YOUR_WORKSPACE_ID  
    Content-Type: application/json
    curl -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_here
    POST /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.)

    Publishing Methods
    Content Types
    Media Handling

    • Text content

    • Title

    Bluesky

    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

    LinkedIn

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

    Facebook

    • 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

    List Posts API
    Accounts API
    Media API

    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

    Charts
    Post Insights
    Hashtag Analysis
    Best Times

    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

    Accounts API
    Posts API
    Media Upload

    Filter by media type: photo, video, gif

    Step 1: Fetch Available Watermarks

    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.

    Step 2: Schedule or Publish a Post with a Watermark

    When creating or scheduling a post, specify the full watermark object in the relevant accounts array. The watermark settings will be applied to all attached media.

    Example Request:

    Parameters

    Field
    Type
    Description

    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)

    Best Practices

    • Use PNG logos with transparent backgrounds for cleaner results.

    • Place watermarks in corners with moderate opacity to protect without distracting.

    • Watermarking is available per account and per post—choose the right watermark for each audience.

    Key Notes & Limitations

    • Plan Requirements: Watermarking images requires the Professional Plan, videos require the Business Plan.

    • Unlimited Media: No limit on the number of photos you can watermark per post.

    • Account-specific: Watermarks are managed and applied per account.

    • Media Orientation: Watermarks are applied consistently regardless of image/video orientation.

    Related Topics

    • Media Options

    • Media Handling

    • Publishing Methods

    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

    Field
    Type
    Description

    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)

    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.

    • Search Required: Always search and select the correct location using the endpoints above before scheduling your post.

    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

    • Publishing Methods

    • Content Types

    • Media Handling

    Authorization: Bearer-API YOUR_API_KEY
  • Publer-Workspace-Id: YOUR_WORKSPACE_ID

  • Endpoint

    Get Best Times to Post

    Description

    Retrieves a day/hour heatmap of posting performance tailored to the audience of the specified account. Optionally include competitor data and restrict to a custom date range.

    URL Parameter

    Parameter
    Type
    Required
    Description

    account_id

    string

    No

    Social account to analyze. Omit for all workspace accounts.

    Query Parameters

    Parameter
    Type
    Required
    Description

    competitors

    string

    No

    For competitor data. true or false (default false).

    competitor_id

    string

    No

    Analyze a specific competitor (requires competitors=true).

    from

    date (YYYY-MM-DD)

    Yes

    Structure

    • Object keyed by day of week (Monday..Sunday).

    • Each day maps to an array of 24 numbers (hour indexes 0..23).

    • Each number is a relative engagement/performance score (higher = better posting time). Use for ranking and heatmap intensity; not a percentage.

    Notes

    • Default window: If no dates are provided, best times are computed from recent history (commonly last 7 days).

    • Workspace/account settings (e.g., “day starts at” and “week starts on”) influence the visualization in the app; the API always returns 24 hourly slots per day.

    • Heatmap scores are relative within the dataset; normalize in your UI if combining multiple accounts.

    • Competitor view requires competitors=true; use competitor_id to focus on a single competitor.

    • Data refreshes automatically (about every 24 hours). Use Sync Insights in the UI for on‑demand refresh.

    Related Resources

    • Charts — Discover chart IDs and fetch chart data

    • Post Insights — Per‑post performance analytics

    • Hashtag Analysis — Hashtag performance

    • Members — Workspace member analytics

    pinterest

    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

    Draft Posts

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

    Overview

    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)

    Endpoint

    Request Headers

    Header
    Required
    Description

    Use the same scheduling endpoint—with a draft state—to save work-in-progress content without publishing.

    Draft Types & Examples

    1. Account-Connected Draft (draft)

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

    Key Features:

    • Must include accounts array with account IDs

    • Can include scheduled_at for future publishing

    • Uses specific network configurations (e.g., facebook, instagram)

    2. Public Workspace Draft (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

    3. Private Draft (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

    Parameters

    Field
    Type
    Required
    Description

    Network Configuration

    • For draft state: Use specific network keys (facebook, instagram, twitter, etc.)

    • For draft_public and draft_private: Use default

    Best Practices

    • 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

    Related Topics

    Polls

    Create and schedule interactive polls on LinkedIn, Mastodon, and Twitter to engage your audience and gather feedback.

    Key Features

    • Cross-Platform Polls: One payload to post polls on multiple networks

    • Flexible Duration: Support for platform-specific duration limits

    • Option Constraints: Enforce character limits and unique choices

    • Scheduling: Publish immediately or at a specified time

    Supported Platforms & Limits

    Network
    Question Field
    Options
    Duration
    Editable
    Notes

    Tip: When sending a multi-network poll, adhere to Twitter’s 25-character option limit and common duration (e.g., 1, 3, 7 days).

    Request Structure

    Use the unified scheduling endpoint:

    Parameters

    Field
    Type
    Description

    Platform-Specific Notes

    Twitter/X

    • Options live in options array; question must be in text.

    • 2–4 options, ≤25 characters each.

    • Cannot edit after publishing.

    LinkedIn

    • Uses separate question and text.

    • Options ≤30 characters.

    • Up to 14-day duration.

    Mastodon

    • Question goes in text.

    • Options ≤50 characters.

    • Poll can be edited after posting.

    Best Practices

    • Keep questions clear and concise.

    • Use unique, contrasting options.

    • Align durations with campaign timelines.

    Related Topics

    LinkedIn PDF Carousels

    Turn multiple images or documents into a scrollable PDF carousel in a single LinkedIn post. Perfect for presentations, portfolios, and multi-page documents.

    Overview

    Include type: "photo" and set details.type: "document" to bundle your media into a PDF carousel. You may upload images, PDFs, Word, or PowerPoint files up to 100 pages/photos.

    Request Structure

    Parameters

    Field
    Type
    Description

    Supported Features & Limitations

    Feature
    Details

    Workflow

    1. Upload Media Use the to upload images or documents and collect their IDs.

    2. Compose Post

      • Set type: "photo", add media IDs.

    Best Practices

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

    Related Topics

    Charts

    The Analytics section provide access to social media analytics data for connected accounts in your workspace. These endpoints allow you to retrieve available charts and their corresponding data for various social media platforms.

    The Charts endpoints let you:

    • Discover which analytics charts are available (and their IDs).

    • Fetch time‑series and comparative data for selected charts.

    Use the returned id values from “List Charts” with “Get Chart Data” to build dashboards and reports.

    Requirements

    Authentication: Bearer API token Scope: analytics Headers:

    • Authorization: Bearer-API YOUR_API_KEY

    • Publer-Workspace-Id: YOUR_WORKSPACE_ID

    Endpoints

    1. List Charts

    Retrieve chart definitions.

    Description

    Returns a list of charts grouped by category (growth, insights, demographics). Different platforms expose different charts.

    Query Parameters

    Parameter
    Type
    Required
    Description

    Account type values: ig_business, fb_page, twitter, linkedin, youtube, tiktok, google, pin_business, pin_personal, threads, wordpress_oauth, in_profile, in_page, mastodon

    Field Descriptions

    Field
    Description

    2. Get Chart Data

    Fetch data for one or more charts by ID. Returns current and previous period blocks for comparison.

    Description

    Supports growth metrics, post insights, and demographics. Chart IDs must come from the “List Charts” endpoint.

    For better performance and lower latency, request chart data in small logical batches of related chart_ids (e.g., growth first, then insights, then demographics) instead of sending every available chart ID in one call.

    URL Parameters

    Parameter
    Type
    Required
    Description

    Query Parameters

    Parameter
    Type
    Required
    Description

    Structure

    Key
    Description

    Usage Notes

    • Always fetch chart IDs from /api/v1/analytics/charts; charts can change over time.

    • If account_id is omitted, results are aggregated across accessible accounts (where the metric supports aggregation).

    • The comparison (previous) window automatically matches the current window length.

    Related Resources

    • - Manage social media accounts

    • — Track hashtag performance

    • — Suggested posting time slots

    • — Member (team) analytics

    Immediate Publishing

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

    Endpoint

    Request Headers

    Header
    Required
    Description

    Request Body

    Use the standard bulk structure. Omit scheduled_at under accounts:

    Key Fields

    • state: must be "scheduled" for immediate publishing

    • networks: per-network content configuration (facebook, twitter, linkedin, etc.)

    Sample Request

    Sample Response

    Status: 200 OK

    Use the returned job_id to poll /api/v1/job_status/{job_id} until status: "completed".

    Important Considerations

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

    Common Issues

    Related Topics

    • - Details on different content formats

    • - Information about uploading and managing media

    • - Platform-specific capabilities and limitations

    Text Posts

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

    Overview

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

    • Publish or schedule text updates simultaneously to multiple platforms

    • Customize each network’s copy to match character limits and conventions

    • Leverage network-specific features: hashtags, mentions, rich formatting

    Key Features

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

    Platform Support & Limitations

    Request Structure

    Below is an example showing a text post scheduled for multiple platforms:

    Required Parameters

    Field
    Description

    Best Practices

    • Optimize per Platform Tailor messaging length and tone: concise on Twitter, detailed on LinkedIn.

    • Use Hashtags Strategically Add relevant tags to boost discoverability; match platform conventions.

    • Schedule for Peak Times Publish when your audience is most active across time zones.

    • Include Clear CTAs Encourage engagement with direct calls-to-action.

    Related Topics

    Recurring Posts

    Automatically publish the same post at regular intervals, indefinitely or until a specified stop condition.

    Endpoint

    Request Headers

    Auto-Scheduling

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

    Endpoint

    Request Headers

    Recycling Posts

    Automatically re-share a post on a regular cadence. Recycling is ideal for evergreen content, reminders, and promotional campaigns.

    Endpoint

    Request Headers

    Pinterest Pins With a Link URL

    Share visually engaging Pins with an external link URL to drive traffic from Pinterest boards.

    Overview

    Create or schedule a Pinterest Pin by setting type: "photo", adding your media, specifying url for the external link, and the album_id to select the destination board.

    Competitor Analysis

    Use the Competitor Analysis endpoints to list competitor accounts and fetch their high‑level analytics (followers, growth, engagement, reach, and posting mix). Combine with Post Insights and Best Times to build a full competitive benchmarking view.

    Requirements

    Authentication: Bearer API token Scope: analytics Headers:

    Multi-Link Posts (Facebook Carousels)

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

    Request Body

    Parameters

    Photo Posts

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

    Key Features

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

    Post Insights

    The Post Insights endpoint retrieves detailed performance analytics for published posts, with powerful filtering, sorting, and pagination. Use it to build per-post dashboards, leaderboards, and competitor comparisons.

    Requirements

    Authentication: Bearer API token Scope: 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/:id
    GET /api/v1/analytics/members
    GET /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_times
    POST /api/v1/posts/schedule/publish

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

    Visible to all workspace members
    Visible only to the creator

    accounts[].id

    string

    Yes (when accounts present)

    Social account ID

    accounts[].scheduled_at

    string

    No

    ISO 8601 timestamp (only for "draft" state)

    as the network key

    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

    Content Types
    Media Handling
    Publishing Methods

    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

    LinkedIn

    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.

    Text Posts
    Platform-Specific Formats
    Publishing Methods

    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

    Media Upload API
    Platform-Specific Formats
    Publishing Methods
    Content Types
    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

    Content Types
    Media Handling
    Network Reference

    1,500

    For business updates

    Pinterest

    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

    Facebook

    10,000

    Full text supported with formatting

    Twitter/X

    280

    25,000 for premium accounts

    LinkedIn

    3,000

    Supports formatting like bold, italic

    Instagram

    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)

    Publishing Methods
    Media Handling
    Content Types

    Google Business

    Header
    Required
    Description

    Authorization

    Yes

    Bearer-API YOUR_API_KEY

    Publer-Workspace-Id

    Yes

    Workspace ID

    Content-Type

    Yes

    application/json

    Accept

    No

    application/json (default)

    Request Body

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

    Key Parameters

    Field
    Type
    Description

    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

    Examples

    Basic Auto-Scheduling

    Next Available Slot

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

    How It Works

    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.

    4. Schedule: Creates the post at the selected time.

    Use Cases

    • Fill Gaps: Keep your queue full without manual scheduling.

    • Engagement Boost: Leverage data-driven timing for better reach.

    • Bulk Campaigns: Auto-schedule large batches within a window.

    • Hands-Off Workflow: Let Publer handle timing so you focus on content.

    Best Practices

    • Define Posting Schedule: Ensure your account has active time slots configured.

    • Reasonable Ranges: Provide a wide enough window for better slot selection.

    • Mix Methods: Combine auto-scheduling with manual posts for flexibility.

    • Monitor Jobs: Poll /api/v1/job_status/{job_id} to confirm success.

    Common Issues

    Issue
    Solution

    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.

    Related Topics

    • Publishing Methods

    • Scheduled Publishing

    • Recurring Posts

    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
        }]
      }
    }
    ,
    bluesky

    show_percentage

    Indicates client should render as percentage.

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

    Accounts API
    Hashtag Analysis
    Best Times
    Members

    End date (inclusive). Defaults to workspace range if omitted with from.

    Header
    Required
    Description

    Authorization

    Yes

    Bearer-API YOUR_API_KEY

    Publer-Workspace-Id

    Yes

    Your workspace identifier

    Content-Type

    Yes

    application/json

    Accept

    No

    application/json (default)

    Request Body

    Include a recurring object under each post:

    Key Fields

    • state: must be "recurring" for recurring posts

    Recurring Parameters

    Parameter
    Type
    Description
    Example

    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

    Examples

    Weekly Recurring Post

    Biweekly Recurring with Limit

    Every other Tuesday and Thursday:

    How It Works

    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 Support

    Platform

    Recurring Support

    Notes

    Facebook

    Full support

    No special requirements

    Instagram

    Full support

    No special requirements

    LinkedIn

    Full support

    No special requirements

    Twitter

    Limited

    Requires 10+ variations using Spintax Generator

    Use Cases

    • Regular reminders (e.g., weekly tips).

    • Monthly newsletters or reports.

    • Annual event notifications (e.g., holidays).

    • Routine promotions or offers.

    Best Practices

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

    • Recurring Posts: Fixed dates/times on a repeating schedule.

    • Recycling Posts: Fills open slots based on your posting calendar.

    Related Topics

    • Recycling Posts

    • Scheduled Publishing

    • Auto-Scheduling

    Header
    Required
    Description

    Authorization

    Yes

    Bearer-API YOUR_API_KEY

    Publer-Workspace-Id

    Yes

    Your workspace identifier

    Content-Type

    Yes

    application/json

    Accept

    No

    application/json (default)

    Request Body

    Include a recycling object in your payload:

    Recycling Parameters

    Field
    Type
    Description

    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)

    Examples

    Basic Recycling

    Recycle every 2 weeks, up to 3 times:

    Recycling with Expiration Date

    Recycle monthly until end of year:

    How It Works

    1. Create a post with recycling settings.

    2. Publer queues the post for reuse.

    3. After each gap interval, the post is republished.

    4. Recycling stops when expire_count or expire_date is reached.

    Platform Limitations

    Due to API limitations and anti-spam policies, recycling has some platform-specific constraints:

    Platform

    Recycling Support

    Notes

    Facebook

    Full support

    No special requirements

    Instagram

    Full support

    No special requirements

    LinkedIn

    Full support

    No special requirements

    Twitter

    Limited

    Requires 10+ variations using Spintax Generator

    Use Cases

    • Promote evergreen blog posts or resources.

    • Remind followers of ongoing events or offers.

    • Keep your feed active with minimal manual effort.

    Best Practices

    • Vary content slightly using Spintax to avoid spam filters.

    • Choose sensible intervals—don’t recycle too frequently.

    • Always set an expiration (expire_count or expire_date).

    • Monitor engagement metrics to adjust recycling strategy.

    Recycling vs. Recurring

    • Recycling fills open slots based on gap and gap_freq—ideal for evergreen content.

    • Recurring publishes at exact times on a fixed repeat schedule (e.g., every Monday at 9 AM).

    Related Topics

    • Recurring Posts

    Key Features
    • 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

    Supported Features & Limits

    Feature
    Details

    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

    Request Structure

    Parameters

    Field
    Type
    Description

    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.

    Workflow

    1. Select Account & Board Add your Pinterest account.id and target album_id.

    2. Upload/Reference Media Upload up to 5 photos or 1 video to Publer, then reference each with its id.

    3. Compose Pin

      • Set type: "photo".

      • Provide text, title, and url.

      • Optionally add alt_text.

    4. Schedule or Publish

      • To schedule, include scheduled_at.

      • To publish now, call /posts/schedule/publish or omit scheduled_at.

    Best Practices

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

    Related Topics

    • Platform-Specific Formats

    • Publishing Methods

    • Content Types

    Authorization: Bearer-API YOUR_API_KEY
  • Publer-Workspace-Id: YOUR_WORKSPACE_ID

  • 1. List Competitors

    Retrieve competitor accounts for the workspace or scoped to a specific social account.

    Description

    • Omit :account_id to list all competitors across the workspace.

    • Provide :account_id to list competitors tied to a single social account.

    URL Parameter

    Parameter
    Type
    Required
    Description

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

    2. Get Competitors Analytics

    Fetch paginated analytics for competitor accounts with filtering, sorting, and date range selection.

    Description

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

    URL Parameter

    Parameter
    Type
    Required
    Description

    account_id

    string

    No

    Scope analytics to one social account (path variant).

    Query Parameters

    Parameter
    Type
    Required
    Description

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

    Notes

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

    Related Resources

    • 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

    networks.facebook
    Field
    Type
    Description

    type

    string

    Must be "carousel".

    text

    string

    Caption shown above the carousel cards.

    sublinks[]

    array

    List of carousel items (max 10).

    sublinks[] Object

    Field
    Type
    Description

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

    Key Notes & Limitations

    • Pages Only: Supported on Facebook Pages. Group posts will include only the first sublink.

    • Max Sublinks: Up to 10 cards per carousel.

    • No Cost: Carousel posts are organic (no ad spend).

    • Syncing: Published carousel posts can only sync back as regular link posts (no carousel structure).

    Workflow

    1. Select Page Choose a Facebook Page account in the accounts array.

    2. Define Sublinks Provide url, title, description, and images for each card.

    3. Arrange Order Order sublinks as they should appear (array index defines order).

    4. Schedule or Publish

      • For scheduled: set scheduled_at under accounts.

      • For immediate: omit scheduled_at and use /posts/schedule/publish.

    Best Practices

    • Engaging Thumbnails Use high-quality images that clearly represent each link.

    • Clear Titles & Descriptions Keep text concise and action-oriented to drive clicks.

    • Focused Carousels Limit to 5–7 cards to avoid overwhelming users.

    • A/B Test CTAs Experiment with LEARN_MORE, SIGN_UP, and other button types.

    Related Topics

    • Platform-Specific Formats

    • Publishing Methods

    • Content Types

    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.

  • Platform Support & Limits

    Platform
    Max Photos
    Photo Size Limit
    Caption Support
    Notes

    Facebook

    Unlimited

    No restriction

    Yes

    No restrictions on photo size.

    Instagram

    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.

    Request Structure

    Below is an example showing a photo post scheduled for multiple platforms.

    Omit scheduled_at for immediate posts.

    Required Parameters

    Field
    Description

    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.

    Media Workflow

    1. Upload Images: Use the Media Handling API to upload files.

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

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

    4. Publish/Schedule: Send the payload to the posts endpoint.

    Best Practices

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

    Related Topics

    • Media Handling

    • Content Types

    • Publishing Methods

    Authorization: Bearer-API YOUR_API_KEY
  • Publer-Workspace-Id: YOUR_WORKSPACE_ID

  • Endpoint

    Get Post Insights

    Retrieve comprehensive analytics for posts within a workspace or a specific social account. Supports competitor analysis, text search, labels, post types, date ranges, member filtering, and multiple sort options.

    Description

    • When :account_id is a specific social account ID, results are limited to that account.

    • When :account_id is omitted, results include all accessible accounts.

    • Enable competitor mode with competitors=true and optionally narrow to a single competitor via competitor_id , see Competitor Analysis how to fetch competitor ids.

    URL Parameter

    Parameter
    Type
    Required
    Description

    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.

    Query Parameters

    Parameter
    Type
    Required
    Description

    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

    Notes

    • Data sources: Metrics come from the official social network APIs. Insights auto‑sync periodically; you can manually sync in the UI for fresher data.

    • Post vs aggregate reach: Post Insights show reach per post. Charts/overview may show total reach across all posts for a time window, so numbers won’t necessarily sum 1:1.

    • Engagement formula: Typically the sum of likes/reactions + comments + shares + saves + post clicks (platform‑dependent).

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

    Related Resources

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

    Posts

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

    Requirements

    • Authentication: Bearer API token

    • Scope: posts

    • Headers:

      • Authorization: Bearer-API YOUR_API_KEY

      • Publer-Workspace-Id: YOUR_WORKSPACE_ID

    Endpoint

    List Posts

    Retrieve posts with optional filters and pagination.

    Query Parameters

    Parameter
    Type
    Required
    Description

    State Values

    Type Values

    Filtering Examples

    • 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

    Related Resources

    • - List social media accounts

    • - Upload and manage media for posts

    • - Post creation endpoints

    Rate Limits

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

    Default Limits

    Limit Window
    Requests Allowed

    2-minute fixed

    100 requests

    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:

    Header
    Description

    Example Response Headers

    When You Exceed the Limit

    If you go over your quota, the API returns:

    • HTTP Status: 429 Too Many Requests

    • Response Body:

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

    Daily Post Limits

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

    Post Limits by Plan

    Platform
    Free Plan
    Professional Plan
    Business Plan

    Important Notes

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

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

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

    • Platform compliance: Limits align with each social network's community guidelines

    Best Practices to Avoid Throttling

    • Cache responses for idempotent or infrequently changing endpoints.

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

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

    • Monitor headers

    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:

    Bulk Scheduling

    Efficiently schedule up to 500 posts across multiple accounts and networks in a single API request. Bulk scheduling in Publer streamlines content planning and helps you stay organized at scale.

    Overview

    Bulk scheduling lets you prepare, customize, and schedule a large number of posts at once—supporting both text and media content for all supported networks. Each post in the bulk payload can have unique content, network targeting, and scheduling options.

    Key Features

    • Create and schedule up to 500 posts in a single API call.

    • Combine multiple social accounts and networks per post.

    • Supports text, images, videos, and more.

    • Choose between Schedule, Auto Schedule, or Recycle modes.

    Request Structure

    Send a POST request to the scheduling endpoint with your bulk payload:

    Endpoint

    Request Headers

    Header
    Required
    Description

    Request Body

    Example Payload:

    Parameters

    Field
    Type
    Description

    Scheduling Modes

    • Schedule: Add scheduled_at to specify exact publish time per account/post.

    • Auto Schedule: Omit scheduled_at and set bulk.state to "auto" to use the account's posting schedule.

    • Recycle: Set bulk.state

    How It Works

    1. Prepare Your Bulk Payload: List each post with its content, targeted networks, and accounts.

    2. Customize Each Post: Add media, captions, hashtags, locations, watermarks, and more individually per post.

    3. Choose Scheduling Mode: Use scheduled_at for manual scheduling or let Publer auto-schedule based on your rules.

    Best Practices

    • Use bulk scheduling for campaigns, product launches, or large-scale social content plans.

    • Individually tailor each post for its platform and audience.

    • Use the scheduling modes for flexibility—manual times for some posts, auto-schedule for others.

    Related Topics

    Link Posts

    Share URLs with rich previews (title, description, image, and call-to-action) across your social networks via the Publer API.

    Overview

    Link posts display a URL preview alongside optional caption text. You control metadata (title, description, images, CTA) to enhance engagement.

    Key Features

    • 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

    Platform Support

    Network
    Preview Elements
    Notes

    Step 1: Extract Link Metadata

    Before scheduling a link post, you can extract rich metadata from any URL using the /posts/links endpoint. This step is optional but highly recommended for accurate previews.

    Use this extracted metadata to build your link post payload.

    Step 2: Create or Schedule a Link Post

    Use the unified scheduling endpoint (/posts/schedule) or the immediate-publish endpoint (/posts/schedule/publish):

    Parameters

    Field
    Type
    Description

    Note: You can also include original_title, original_description, and original_images if you pre‐fetch metadata yourself, but only the link.* fields above are required.

    Workflow

    1. Extract Metadata Use /posts/links to fetch title, description, and images from your target URL.

    2. Compose Metadata Define url, title, description, and images in the link object.

    Best Practices

    • Provide Complete Metadata: Supply title, description, and images for compelling previews.

    • Optimize Image Dimensions: Match each network’s recommended preview size for best display.

    • Use Clear CTAs: Select a relevant call_to_action to guide user action.

    Related Topics

    Video Posts

    Dynamic, high-impact video content for social networks. Video posts drive significantly more views and shares than static media, and the Publer API makes it easy to upload, configure, and schedule videos across multiple platforms.

    Overview

    Programmatically create and schedule video content—standard uploads, short-form (Reels/Shorts/Stories), and rich metadata (titles, descriptions, custom thumbnails)—while meeting each network’s format rules and size limits.

    Google Business Profiles: Updates, Photos, Events & Offers

    Share updates, photos, events, and special offers on your Google Business Profile via the Publer API. Each post type has its own fields—use the right payload to drive engagement and conversions.

    Request Examples

    1. Update Post

    Media Handling

    Manage your media assets before attaching them to posts. Publer’s API supports direct uploads and URL imports, returning media IDs you can reference when creating or updating posts.

    Overview

    Before including media in your social media posts, you must first upload those files to Publer's servers. The API provides two methods for uploading media:

    1. Direct file upload

    GET /api/v1/analytics/charts
    GET /api/v1/analytics/:account_id/chart_data
    POST /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_id
    GET /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_insights

    expire_count

    number

    Maximum number of reposts

    expire_date

    string

    ISO date to stop recycling (alternative to expire_count)

    Pinterest

    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.

    Twitter

    4

    5 MB

    Yes

    Supports only up to 4 photos per post.

    LinkedIn

    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

    and throttle your client.
  • 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

    Requesting Higher Limits
    [email protected]

    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

    to
    "recycle"
    to enable cyclical republishing based on the account's recycle settings.
  • Recurring posts are not supported in bulk scheduling.

  • Submit: Send your payload to /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

    Publishing Methods
    Content Types
    Media Handling

    "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]

    Pinterest

    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:00
    2025-07-21T13:29+02:00

    to

    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

    Accounts API
    Media API
    Create Posts

    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.

  • Facebook

    Title, description, images, CTA

    Full link card support

    LinkedIn

    Title, description, images, CTA

    Full link card support

    Twitter/X

    Automatic card preview

    Metadata driven by Twitter Card tags

    Pinterest

    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

    Media Handling
    Content Types
    Publishing Methods

    Requires uploaded images in media

    Key Capabilities
    • Cross-Platform Publishing One API call to distribute videos to Facebook, Instagram, YouTube, TikTok, LinkedIn, and more.

    • Format Versatility Support for standard videos, short-form (Reels, Shorts), and Stories.

    • Rich Metadata Attach titles, captions, and custom thumbnail selections.

    • Advanced Scheduling Schedule per time zone or publish immediately; poll job status for completion.

    Platform Support & Specifications

    Network
    Video Types
    Duration
    Size Limit
    Aspect Ratio
    Additional Features

    Facebook

    Standard, Reels, Story

    Standard: up to 5 h Reels: 3–90 s Stories: ≤60 s

    < 2 GB

    Flexible

    Auto-captions, premiere scheduling

    Instagram

    Feed, Reels, Story

    Feed: any Reels: 3 s–15 min Stories: ≤60 s

    Request Structure

    Schedule a video post using the unified scheduling endpoint:

    Required Parameters

    Field
    Description

    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.

    Workflow for Creating Video Posts

    1. Upload Video Use the Media Handling endpoint to upload your video.

    2. Receive Media ID Note the returned id for referencing in your post payload.

    3. Configure Thumbnails Upload or select thumbnail images and include their IDs/URLs.

    4. Compose & Schedule Build your post object, set state and scheduled_at, then send to /posts/schedule.

    5. Monitor Job Poll /api/v1/job_status/{job_id} until status is completed.

    Best Practices

    • Select Engaging Thumbnails Choose a frame or custom image that drives clicks.

    • Provide Clear Titles & Descriptions Improve accessibility and SEO with detailed metadata.

    • Validate Platform Requirements Confirm aspect ratio, encoding, and file format (MP4/H.264 recommended).

    Related Topics

    • Media Handling

    • Content Types

    • Publishing Methods

    General news or announcement with an image and a CTA button.

    2. Photo Post

    Standalone photo update (no special details).

    3. Event Post

    Promote an upcoming event with start/end times and an optional link.

    4. Offer Post

    Advertise discounts or promotions with coupon codes and terms.

    Parameters

    Field
    Type
    Description

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

    Supported Features & Limits

    Feature
    Details

    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

    Workflow

    1. Select Profile Choose the Google Business Profile in accounts[].id.

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

    3. Add Media Upload or reference one photo via the .

    4. Compose & Schedule Build your JSON, set state and scheduled_at, then POST to /posts/schedule.

    Best Practices

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

    Related Topics

    • Platform-Specific Formats

    • Publishing Methods

    • Content Types

    Upload from URL

    Once uploaded, you'll receive a media ID that can be referenced in your post requests.

    Direct File Upload

    Use this method when you have local media files that you want to upload directly.

    Limitation

    • Maximum file size for direct uploads: 200MB per file.

    • Requests exceeding 200MB will be rejected (typically with HTTP 413 Payload Too Large). For larger files, use the Upload from URL method.

    Request Format

    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)

    Upload from URL

    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.

    Checking Upload Status

    Using Media in Posts

    Once you've uploaded media and have the media ID, you can reference it in your post requests:

    Supported Media Types

    Images

    • Supported formats: JPG, PNG, GIF, WEBP

    • Recommended dimensions: Varies by platform (see Networks Reference)

    • Maximum file size: Varies by platform, generally 5-10MB

    Videos

    • 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

    Documents

    • Supported formats: PDF

    • Maximum file size: 100MB

    • Supported networks: LinkedIn only

    Network Validation

    The validity object in the media upload response indicates which networks and post types can use the uploaded media. This helps prevent errors when attempting to use incompatible media in your posts.

    For example, if validity.instagram.reel is false, the uploaded media cannot be used for Instagram Reels.

    Best Practices

    Image Optimization

    1. Resolution: Use appropriate image resolutions for each platform

    2. Aspect ratio: Follow recommended aspect ratios to avoid cropping

    3. File size: Optimize images for web to reduce file size

    4. Alt text: Always include descriptive alt text for accessibility

    Video Optimization

    1. Format: Use MP4 with H.264 encoding for maximum compatibility

    2. Dimensions: Use 1080p (1920x1080) for standard videos

    3. Aspect ratio: 16:9 for horizontal, 9:16 for vertical/stories/reels

    4. Duration: Keep videos under platform limits

    5. Thumbnails: Consider uploading custom thumbnails for videos

    General Tips

    1. Pre-check compatibility: Review the validity object before using media

    2. Error handling: Implement robust error handling for upload failures

    3. Caching: Cache media IDs to avoid unnecessary re-uploads

    Related Topics

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

    Post Insights

    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.

    Reels, Shorts & Stories

    Short-form, immersive content formats for deep engagement. Use Publer’s API to schedule or publish Reels (Instagram & Facebook), Shorts (YouTube), and Stories (Instagram & Facebook) with a single JSON payload.

    Supported Formats & Specs

    Format
    Platform
    Max Duration
    Aspect Ratio
    Max Size
    Notes

    Request Structure

    Send to the scheduling endpoint or use /posts/schedule/publish for immediate posting:

    1. Instagram/Facebook Reel

    2. YouTube Short

    3. Instagram/Facebook Story

    Common Parameters

    Field
    Type
    Description

    Workflow

    Reels

    1. Upload: Use to upload vertical video (9:16).

    2. Compose: Set "details.type": "reel", optional audio and feed flags.

    3. Schedule: Provide scheduled_at or publish immediately.

    Shorts

    1. Upload: Upload video ≤ 60 sec, 9:16 ratio.

    2. Configure: Set "details.type": "short" and privacy.

    3. Add Title/Text: Populate title and text.

    Stories

    1. Upload: Add photo or video ≤ 15 sec.

    2. Tag as Story: Use "details.type": "story".

    3. Caption: Add text overlay.

    Best Practices

    • Use high-quality, platform-compliant media (9:16 ratio).

    • Rename Reel audio to match branding.

    • Schedule according to audience peak times.

    Related Topics

    Creating Posts

    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

    • Scopes: posts, media

    • Headers:

      • Authorization: Bearer-API YOUR_API_KEY

      • Publer-Workspace-Id: YOUR_WORKSPACE_ID

    Core Concepts

    Asynchronous Workflow

    1. Submit Request to /posts/schedule or /posts/schedule/publish

    2. Receive { "job_id": "…" }

    3. Poll /job_status/{job_id} until status: "completed"

    Common Request Structure

    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

    Endpoints

    Publishing Methods

    The state parameter determines how your content will be handled:

    Content Types

    The type parameter specifies the content format:

    Network Providers

    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

    Job Status

    Poll your job with:

    Response:

    Common Patterns

    Network-Specific Content

    To customize content for specific platforms:

    Media References

    Media files must be pre-uploaded and referenced by ID, see :

    Next Steps

    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

    Post Callbacks

    Automate follow-up actions when you publish or schedule posts: auto-share to other accounts, post follow-up comments (or thread posts on some networks), or auto-delete/hide content after specified conditions are met.

    Overview

    Post callbacks are automation features you include per-account in the API request when creating posts. Callbacks are configured inside each accounts[] entry. The main callback types:

    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

    Media Upload API

    < 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

    LinkedIn

    Standard

    3 s–15 min

    < 2 GB

    1:2.4–2.4:1

    Native profile/page posting

    Pinterest

    Standard

    4 s–15 min

    < 2 GB

    —

    —

    Twitter/X

    Standard

    Up to 10 min

    < 512 MB

    Flexible

    Alt text support

    Telegram

    Standard

    Unlimited

    < 50 MB

    Flexible

    —

    Mastodon

    Standard

    Unlimited

    < 40 MB

    Up to 1920×1200 px

    —

    Threads

    Standard

    Up to 5 min

    < 1 GB

    Flexible

    —

    Bluesky

    Standard

    Up to 3 min

    < 50 MB

    Flexible

    —

    networks.{provider}.text

    Optional caption or description.

    accounts[].id

    Target social media account ID.

    accounts[].scheduled_at*

    ISO 8601 timestamp (omit for immediate publishing).

    Listing Media
    Media Upload

    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.

    Schedule: Set 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)

    Media API
    Platform-Specific Formats
    Publishing Methods
    Content Types

    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

    ,
    bluesky
    .

    Endpoint

    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

    Media Handling
    Publishing Methods
    Content Types
    Media Handling
    Network Reference

    recurring

    carousel

    AutoShare — automatically share a published post to other social accounts
  • Follow-up Comments — schedule one or multiple comments (or threaded posts) tied to a post

  • Auto-Delete / Auto-Hide — automatically remove or hide posts after conditions are met

  • Conditions are represented with a structured conditions object (relation + clauses) and can combine Time (age), Reach and Engagements checks using AND/OR.

    Endpoints

    • Schedule with callbacks: POST /api/v1/posts/schedule

    • Publish now with callbacks: POST /api/v1/posts/schedule/publish

    Callbacks live inside each account object in your request payload.

    Request structure (top-level)

    • bulk

      • state (e.g., "scheduled")

      • posts[]:

        • networks: { <network_name>: { type, text, details, ... } }

        • accounts[]:

          • id

          • scheduled_at (optional)

          • share (optional)

          • comments (optional array)

    Conditions object

    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.

    Auto-Sharing

    Automatically share the link of the published post to the specified accounts.

    Fields:

    • share.account_ids (string[]) — target account IDs to share to

    • share.text (string) — caption for the share (fallback: original post text where supported)

    • share.conditions (object) — when the share should run (see Conditions object)

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

    Follow-up Comments

    Schedule comments on the published post (or create follow-up posts/threads on some networks).

    Fields:

    • comments[]:

      • text (string) — comment body (text, hashtags, links, emoji)

      • language (string, optional)

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

    Auto-Delete / Auto-Hide

    Automatically delete or hide a post when conditions are satisfied.

    Fields:

    • delete.conditions (object) — conditions triggering deletion/hide (see Conditions object)

      • Use conditions.clauses.age to set minimum time before deletion

    • delete.hide (boolean) — true to request hide instead of delete (platform-dependent)

    Example:

    Supported / unsupported:

    • Auto-delete supported for most scheduled networks except:

      • Not available for Instagram API (auto-delete not supported)

      • Not available for TikTok accounts

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

    Request Structure

    Full example

    Best practices

    • Use performance-based conditions to avoid premature callbacks (e.g., only share if the post reached a threshold).

    • Respect audience time zones when scheduling shares and comments.

    • Space out repeated shares across accounts using share.delay to avoid spam signals.

    • 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 & Post Presets

    • Recurring posts: add callbacks during scheduling so each recurrence includes them automatically.

    • Post Presets: configure default follow-up comments, auto-share targets, and default auto-delete/hide rules in Post Presets inside Publer. Presets use the same conditions model.

    Limitations & notes

    • Some networks convert comments into separate posts/threads (Twitter/X, Mastodon, BlueSky, Threads).

    • Follow-up comments are not supported by Pinterest, TikTok, Facebook Personal Profiles, and Google Business Profiles due to API limitations.

    • Auto-delete is not available for Instagram, TikTok, posts published via reminders, or some story formats.

    • Performance-based conditions depend on platform metrics; metrics may arrive with delay.

    Related Topics

    • 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

    Facebook Text Posts with Background

    Create and schedule Facebook status updates with vibrant backgrounds to boost engagement and visual appeal.

    Request Body

    Include text_format_preset_id in details under the facebook network:

    Submit Request  →  Receive Job ID  →  Poll Job Status  →  Processing Complete
    {
      "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)

    Parameters
    Field
    Type
    Description

    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.

    Background Presets

    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

    Key Notes & Limitations

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

    Best Practices

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

    Related Topics

    • Platform-Specific Formats

    • Publishing Methods

    • Content Types

    TikTok Video & Multi-Photo Posts

    Publish or schedule TikTok videos and multi-photo (carousel) posts using the Publer API. This feature supports all TikTok-specific options, including privacy, comments, branded content, and more.

    Overview

    Publer enables you to directly post or schedule TikTok videos and multi-photo posts (carousels) from your app or workflow.

    You can only post to one TikTok account at a time—TikTok does not allow duplicate content or posting to multiple accounts simultaneously.

    • Video posts: Upload and schedule single video posts. Supports cover selection, privacy, comment/duet/stitch toggles, and branded content disclosures.

    • Multi-photo posts (carousels): Upload and schedule up to 35 photos, each with an optional caption, as a single post. Supports music auto-add, privacy, and engagement options.

    Notice: TikTok Video Publishing & Link Availability

    When posting a video to TikTok, the API does not immediately return a URL to the published post. TikTok first processes the video after upload and only makes the public link available once processing is complete.

    • After posting a video: The returned response will not contain the TikTok post URL.

    • To obtain the published TikTok video link: Retrieve your post later via the . Once TikTok finishes processing, the link will be included in the post data.

    How It Works

    To schedule or publish a TikTok post, use the or API endpoint with a networks.tiktok object describing your post.

    Key Rules

    • No recurring or recycled videos: TikTok does not allow duplicate content.

    • Watermarks: Not supported due to TikTok API limits.

    • Privacy and engagement: Options are synced from TikTok and may vary by account type, check your account details from .

    • Thumbnails (Videos): You can select a cover frame when posting automatically.

    Video Post Example

    Multi-Photo Post (Carousel) Example

    TikTok-Specific Parameters

    Video Post Parameters

    Field
    Type
    Required
    Description

    Carousel (Multi-Photo) Post Parameters

    Field
    Type
    Required
    Description

    Tips & Limitations

    • No GIF/video mixing: Carousel posts cannot mix photos, GIFs, or videos.

    • Privacy: "Everyone" is only available if the TikTok account is public.

    • Branded content: Cannot be private. Once posted, branded content is permanently labeled.

    • No recurring or recycled posts: TikTok blocks duplicate content.

    Related Topics

    Content Types

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

    Supported Content Types

    {
      "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

    Instagram

    photo, video, carousel, story, reel

    Twitter/X

    status, photo, video, link, gif, poll

    LinkedIn

    status, photo, video, link, document, poll, gif

    Pinterest

    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

    Best Practices

    Content Optimization

    • Test each format on a single account before scaling.

    • Use network-specific overrides to tailor text length, captions, and metadata.

    • Always provide alt_text for images to enhance accessibility.

    • Follow each platform’s style and character limits for optimal engagement.

    Technical Considerations

    • Preprocess media (resize, compress) before upload to meet platform requirements.

    • Verify media upload success before referencing media IDs in your post payload.

    • Review provider documentation for specific limits (e.g., LinkedIn document size, TikTok clip length).

    • Poll the job status endpoint to ensure the content was processed and published without errors.

    Related Topics

    • 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

    Facebook

    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

    Posts
    Immediate Publishing
    Manual Scheduling
    Accounts
    Twitter/X Long-Form Posts
    Content Types Overview

    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
                }
              }
            }
          }
        ]
      }
    }

    Twitter/X Community Posts

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

    Overview

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

    • 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

    Example Request

    Set the community object inside the details for the twitter network configuration:

    Field
    Type
    Description

    How to Find the Community ID

    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.

    Important Notes

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

    Best Practices

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

    Related Topics

    Publishing Methods

    A concise guide to all content publishing methods available via the Publer API. Choose the method that best fits your workflow, from instant publishing to automated recycling and recurring schedules.

    Available Methods

    Method
    Use Case
    Key Parameters
    Business Value

    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)

    Twitter/X Long-Form Posts
    Content Types Overview
    {
      "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

    Immediate Publishing

    Send your post to networks right away.

    Endpoint:

    Request example:

    Implementation Notes

    • Omit scheduled_at entirely

    • Content is processed immediately via the schedule/publish endpoint

    • Supports all content types and network-specific options

    Learn more about immediate publishing


    Scheduled Publishing

    Plan posts for future dates and times across multiple networks.

    Endpoint:

    Request example:

    Implementation Notes

    • 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

    Learn more about scheduled publishing


    Draft Posts

    Save work-in-progress content for review or refinement.

    Endpoint:

    Request example (private draft):

    Visibility Options

    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

    Learn more about draft posts


    Auto-Scheduling

    Let Publer pick the best posting times within a date range.

    Endpoint:

    Before auto-scheduling, you need to keep in mind that:

    • You need a posting schedule. Posting schedules are account-specific. You can have only one posting schedule per account, however, it can consist of many time slots.

    • If you want the same posting schedule across multiple social accounts, you can do so by Duplicating Settings.

    Request example:

    Key Auto-Scheduling Parameters

    Parameter

    Type

    Required

    Description

    auto

    boolean

    Yes

    Set to true to enable auto-scheduling

    range.start_date

    string

    Yes

    ISO 8601 timestamp for earliest possible posting time

    range.end_date

    string

    No

    ISO 8601 timestamp for latest possible posting time

    Learn more about auto-scheduling


    Recycling Content

    Automatically repost content multiple times on a defined cadence.

    Endpoint:

    To Recycle a post:

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

    Learn more about recycle posts


    Recurring Posts

    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)

    Learn more about recurring posts


    Response Handling

    All publishing methods return a job ID for asynchronous processing:

    Checking Job Status

    Always verify success by checking the job status:

    Example success response:

    Job Status Values

    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

    Advanced Usage Tips

    • Network-specific content: Override content for specific platforms

    • Multi-account publishing: Target multiple accounts in a single request

    Hashtag Analysis

    The Hashtag Analysis endpoints help you understand how hashtags perform across your workspace or a specific account. Use them to rank, filter, and retrieve top posts for any hashtag.

    Requirements

    Authentication: Bearer API token Scope: analytics Headers:

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

    Immediate
    Scheduled
    Draft
    Auto-scheduled
    Recycled
    Recurring
    Authorization: Bearer-API YOUR_API_KEY
  • Publer-Workspace-Id: YOUR_WORKSPACE_ID

  • Endpoints

    1. Get Hashtag Insights

    Retrieve aggregated analytics for hashtags used in published posts. Supports filtering by date range, account, member, and search, plus sorting and pagination.

    Description

    Returns a paginated list of hashtags with totals for posts, reach, engagement, and related metrics, plus up to 3 recent posts per hashtag and a hashtag performance score.

    URL Parameter

    Parameter
    Type
    Required
    Description

    account_id

    string

    No

    Limit to a single social account. Omit for all workspace accounts.

    Query Parameters

    Param
    Type
    Required
    Description

    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.

    2. Get Hashtag Performing Posts

    Retrieve up to 6 top posts that used a specific hashtag, with full per‑post analytics.

    URL Parameter

    Parameter
    Type
    Required
    Description

    account_id

    string

    No

    Limit to a single social account. Omit for all workspace accounts.

    Query Parameters

    Param
    Type
    Required
    Description

    hashtag

    string

    Yes

    Hashtag to analyze (with #).

    from

    date (YYYY-MM-DD)

    No

    Start date (inclusive).

    to

    date (YYYY-MM-DD)

    No

    Notes

    • Time range: Defaults to the workspace’s default range when not provided. “Last X Days” excludes partial data for the current day.

    • Sorting & ranking: Use sort_by and sort_type to rank by Posts, Reach, Reactions (likes), Comments, Shares, or Video Views. UI columns can be reordered client‑side.

    • Data freshness: Insights auto‑refresh every ~24h; you can manually sync in the UI for real‑time updates.

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

    Related Resources

    • 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_insights
    GET /api/v1/analytics/hashtag_performing_posts

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

    Networks

    Detailed platform-specific capabilities, content support, and limitations for all social networks available via the Publer API.

    Supported Networks

    Network

    Provider

    Content Types

    Media Support

    Character Limit

    Network-Specific Details

    Facebook

    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:

    Instagram

    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:

    Twitter/X

    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:

    LinkedIn

    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:

    Pinterest

    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:

    Google Business Profile

    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:

    TikTok

    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:

    YouTube

    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:

    Telegram

    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:

    Mastodon

    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:

    Threads

    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:

    Bluesky

    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:

    Media Specifications

    Image Requirements

    Video Requirements

    Best Practices

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

    Related Topics

    • - Detailed information about different content formats

    • - Guide to uploading and managing media files

    • - Options for publishing to different networks

    Link posts
  • Carousel posts

  • Stories

  • Reels
    Reels: 3-90 seconds
    Polls

    GIFs limited to 15MB

    Document posts (PDFs)
    Shorts need to be shot vertically and be up to 3 minutes long.
    Gif Posts

    LinkedIn

    1200x627px

    1.91:1

    5MB

    Pinterest

    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

    LinkedIn

    1920x1080px

    16:9

    3s - 15m

    5GB

    Pinterest

    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

    facebook

    status, photo, video, link, carousel

    Images, videos, links

    10,000

    Instagram

    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

    linkedin

    status, photo, video, link, document, polls

    Images, videos, documents, links

    3,000

    Pinterest

    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

    Facebook

    1200x630px

    1.91:1

    8MB

    Instagram

    1080x1080px

    1:1 to 4:5

    8MB

    Twitter

    1200x675px

    16:9

    5MB

    Network

    Optimal Dimensions

    Aspect Ratio

    Duration

    Max File Size

    Facebook

    1280x720px

    16:9

    1s - 240m

    10GB

    Instagram

    1080x1920px

    9:16

    3s - 60m

    650MB

    Twitter

    Content Types
    Media Handling
    Publishing Methods

    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"}]
    }

    Get Current User

    get

    Retrieves information about the currently authenticated user.

    Authorizations
    AuthorizationstringRequired

    API key authentication. Format: "Bearer-API YOUR_API_KEY"

    Responses
    200

    Successful operation

    application/json
    401

    Unauthorized

    application/json
    403

    Permission denied or missing required scope

    application/json
    get
    /users/me

    List Workspaces

    get

    Retrieves a list of all workspaces that the authenticated user has access to.

    Authorizations
    AuthorizationstringRequired

    API key authentication. Format: "Bearer-API YOUR_API_KEY"

    Responses
    200

    Successful operation

    application/json
    401

    Unauthorized

    application/json
    403

    Permission denied or missing required scope

    application/json
    get
    /workspaces

    Get Media Options

    get

    Retrieves albums and watermarks for specified accounts in a workspace.

    Authorizations
    AuthorizationstringRequired

    API key authentication. Format: "Bearer-API YOUR_API_KEY"

    Path parameters
    workspace_idstringRequired

    ID of the workspace to retrieve media options from

    Query parameters
    accountsstring[]Required

    Array of account IDs to filter media options by

    Responses
    200

    Successful operation

    application/json
    401

    Unauthorized

    application/json
    403

    Permission denied

    application/json
    get
    /workspaces/{workspace_id}/media_options

    Delete Multiple Posts

    delete

    Deletes one or multiple posts from the workspace specifying exact post IDs. Authorization rules apply to ensure users can only delete posts they have permission to delete.

    Authorizations
    AuthorizationstringRequired

    API key authentication. Format: "Bearer-API YOUR_API_KEY"

    Query parameters
    post_idsstring[]Required

    Array of post IDs to delete. Can include both MongoDB ObjectIDs and PostgreSQL IDs.

    Header parameters
    Publer-Workspace-IdstringRequired

    ID of the workspace containing the posts

    Responses
    200

    Posts deleted successfully

    application/json
    401

    Unauthorized

    application/json
    403

    Permission denied or missing required scope

    application/json
    delete
    /posts

    List Accounts

    get

    Retrieves a list of social media accounts available in the specified workspace.

    Authorizations
    AuthorizationstringRequired

    API key authentication. Format: "Bearer-API YOUR_API_KEY"

    Header parameters
    Publer-Workspace-IdstringRequired

    ID of the workspace to retrieve accounts from

    Responses
    200

    Successful operation

    application/json
    401

    Unauthorized

    application/json
    403

    Permission denied or missing required scope

    application/json
    get
    /accounts

    Get Signatures for Accounts

    get

    Retrieves signatures associated with specified accounts in a workspace.

    Authorizations
    AuthorizationstringRequired

    API key authentication. Format: "Bearer-API YOUR_API_KEY"

    Path parameters
    workspace_idstringRequired

    ID of the workspace to retrieve signatures from

    Query parameters
    accountsstring[]Required

    Array of account IDs to filter signatures by

    Responses
    200

    Successful operation

    application/json
    401

    Unauthorized

    application/json
    403

    Permission denied or missing required scope

    application/json
    get
    /workspaces/{workspace_id}/signatures

    Update Post

    put

    Updates an existing post. The behavior differs depending on whether the post is already published or not.

    Authorizations
    AuthorizationstringRequired

    API key authentication. Format: "Bearer-API YOUR_API_KEY"

    Path parameters
    idstringRequired

    ID of the post to update

    Header parameters
    Publer-Workspace-IdstringRequired

    ID of the workspace containing the post

    Body
    Responses
    200

    Post updated successfully

    application/json
    401

    Unauthorized

    application/json
    403

    Forbidden - You cannot update a post that has been published with approval

    application/json
    422

    Unprocessable Entity - Error message explaining why the post couldn't be updated

    application/json
    put
    /posts/{id}

    Get Analytics Members Data

    get

    Retrieves analytics data for workspace members showing their posting activity and engagement metrics.

    Authorizations
    Query parameters
    fromstring · dateRequired

    Start date for analytics data range (YYYY-MM-DD format). Filters data from this date onwards

    Example: {"value":"2024-01-01"}
    tostring · dateRequired

    End date for analytics data range (YYYY-MM-DD format). Filters data up to this date

    Example: {"value":"2024-12-31"}
    account_idstringOptional

    Optional account ID to filter analytics data for a specific social media account

    Example: {"value":"63c675b54e299e9cf2b667ea"}
    Header parameters
    Publer-Workspace-IdstringRequired

    ID of the workspace to retrieve members from

    Responses
    200

    Members analytics data with performance metrics

    application/json
    401

    Unauthorized

    application/json
    403

    Permission denied - requires analytics access or paying subscription

    application/json
    get
    /analytics/members

    List Media

    get

    Retrieves a paginated list of media items from the user's library. The endpoint supports filtering by various parameters and can also retrieve specific media items by their IDs.

    Authorizations
    AuthorizationstringRequired

    API key authentication. Format: "Bearer-API YOUR_API_KEY"

    Query parameters
    idsstring[]Optional

    Specific media IDs to retrieve. If provided, pagination and other filters are ignored

    pageintegerOptional

    Page number for pagination (0-based)

    usedboolean[]Required

    Filter by used status

    searchstringOptional

    Search term to filter media by name or caption

    Header parameters
    Publer-Workspace-IdstringRequired

    ID of the workspace to retrieve media from

    Responses
    200

    Successful operation

    application/json
    401

    Unauthorized

    application/json
    403

    Permission denied or missing required scope

    application/json
    get
    /media

    Search for Facebook locations

    get

    Search and retrieve Facebook locations based on a query string.

    Authorizations
    Query parameters
    qstringRequired

    Search query for Facebook locations

    Responses
    200

    List of Facebook locations matching the search query

    application/json
    403

    Authentication failure or invalid token

    application/json
    422

    Invalid request or Facebook API error

    application/json
    get
    /locations/facebook

    Search for Instagram locations

    get

    Search and retrieve Instagram locations based on a query string.

    Authorizations
    Query parameters
    qstringRequired

    Search query for Instagram locations

    Responses
    200

    List of Instagram locations matching the search query

    application/json
    403

    Authentication failure, invalid token, or no Instagram account with Facebook login

    application/json
    422

    Invalid request or Instagram API error

    application/json
    get
    /locations/instagram

    Search for Threads locations

    get

    Search and retrieve Threads locations based on a query string.

    Authorizations
    Query parameters
    qstringRequired

    Search query for Threads locations

    Responses
    200

    List of Threads locations matching the search query

    application/json
    403

    Authentication failure, invalid token, or no Threads account

    application/json
    422

    Invalid request or Threads API error

    application/json
    get
    /locations/threads

    Get Best Times to Post for Account

    get

    Retrieves the optimal posting times for a specific social media account based on historical analytics data. Returns a heatmap of posting performance across days of the week and hours of the day, tailored to the specified account's audience engagement patterns.

    Authorizations
    Path parameters
    account_idstringOptional

    Social media account ID to analyze posting times for. When provided, analysis is specific to this account's performance data

    Query parameters
    competitorsstring · enumOptional

    Include competitor data in best times analysis. Set to 'true' to analyze competitor posting patterns

    Possible values:
    competitor_idstringOptional

    Specific competitor ID to analyze. Used in conjunction with competitors=true parameter

    fromstring · dateRequired

    Start date for analytics data range (YYYY-MM-DD format). Filters data from this date onwards

    Example: {"value":"2024-01-01"}
    tostring · dateRequired

    End date for analytics data range (YYYY-MM-DD format). Filters data up to this date

    Example: {"value":"2024-12-31"}
    Header parameters
    Publer-Workspace-IdstringRequired

    ID of the workspace to retrieve best times from

    Responses
    200

    Best times to post data organized by day of the week and hour for the specific account

    application/json
    401

    Unauthorized

    application/json
    403

    Permission denied - requires analytics access or paying subscription

    application/json
    get
    /analytics/{account_id}/best_times

    Get Available Analytics Charts

    get

    Retrieves a list of available analytics charts filtered by account type and chart type. Charts include growth metrics (followers, connections), insights (engagement, reach), and demographics (countries, ages).

    Authorizations
    Query parameters
    account_typestring · enumOptional

    Social media platform type to filter charts for (e.g., 'ig_business', 'fb_page', 'twitter', 'linkedin', 'youtube', 'tiktok', 'google', 'pin_business')

    Possible values:
    Header parameters
    Publer-Workspace-IdstringRequired

    ID of the workspace to retrieve charts from

    Responses
    200

    List of available charts with metadata

    application/json
    401

    Unauthorized

    application/json
    403

    Permission denied or missing required scope

    application/json
    get
    /analytics/charts

    Get Analytics Chart Data

    get

    Retrieves analytics data for specific charts by their IDs. Returns current and previous period data for comparison. Supports growth metrics, post insights, and demographic data.

    Authorizations
    Path parameters
    account_idstringOptional

    Optional account ID to filter analytics data for a specific social media account

    Query parameters
    chart_idsstring[]Required

    Array of chart IDs to retrieve data for. Use chart IDs from the /analytics/charts endpoint

    Example: {"value":["followers","post_engagement","post_reach"]}
    fromstring · dateOptional

    Start date for analytics data (YYYY-MM-DD format)

    tostring · dateOptional

    End date for analytics data (YYYY-MM-DD format)

    Header parameters
    Publer-Workspace-IdstringRequired

    ID of the workspace to retrieve data from

    Responses
    200

    Analytics chart data with current and previous period values

    application/json
    401

    Unauthorized

    application/json
    403

    Permission denied or missing required scope

    application/json
    get
    /analytics/chart_data

    List Competitors

    get

    Retrieves a list of competitor accounts for the workspace or for a specific social media account.

    Authorizations
    Path parameters
    account_idstringOptional

    ID of the social media account to retrieve competitors for.

    Header parameters
    Publer-Workspace-IdstringRequired

    ID of the workspace to retrieve competitors from

    Responses
    200

    Successful operation

    application/json
    401

    Unauthorized

    application/json
    403

    Permission denied or missing required scope

    application/json
    get
    /competitors/{account_id}

    Get Competitors Analytics

    get

    Retrieves analytics data for competitor accounts, including engagement metrics, follower counts, and post performance statistics.

    Authorizations
    Query parameters
    account_idstringOptional

    ID of the social media account to filter competitors analytics for

    competitor_idstringOptional

    Specific competitor account ID to analyze

    querystringOptional

    Search filter for competitor account names

    fromstring · dateOptional

    Start date for analytics data (ISO 8601 format, e.g., 2023-01-01)

    tostring · dateOptional

    End date for analytics data (ISO 8601 format, e.g., 2023-12-31)

    pageintegerOptional

    Page number for pagination (default: 0)

    sort_bystring · enumOptional

    Field to sort results by

    Possible values:
    sort_typestring · enumOptional

    Sort direction

    Possible values:
    Header parameters
    Publer-Workspace-IdstringRequired

    ID of the workspace to retrieve competitors analytics from

    Responses
    200

    Successful operation

    application/json
    401

    Unauthorized

    application/json
    403

    Permission denied - requires analytics access or paying subscription

    application/json
    422

    Unprocessable entity - service error

    application/json
    get
    /competitors/{account_id}/analytics

    Get Post Post Insights

    get

    Retrieves comprehensive analytics data for published posts with advanced filtering, sorting, and pagination capabilities.

    Authorizations
    Path parameters
    account_idstringOptional

    Filter posts for a specific social media account ID. If omitted, includes all workspace accounts. Used with competitors parameter for competitor-specific analysis

    Query parameters
    competitorsstring · enumOptional

    Include competitor analysis data. Set to 'true' to retrieve competitor post insights

    Possible values:
    competitor_idstringOptional

    Specific competitor account ID to analyze when competitors=true. Works in conjunction with account_id parameter

    fromstring · dateRequired

    Start date for post insights data range (YYYY-MM-DD format). Filters posts scheduled on or after this date

    Example: {"value":"2024-01-01"}
    tostring · dateRequired

    End date for post insights data range (YYYY-MM-DD format). Filters posts scheduled on or before this date

    Example: {"value":"2024-12-31"}
    querystringOptional

    Search query to filter posts by text content, title, link description, or video title using case-insensitive matching

    postTypestring · enumOptional

    Filter posts by specific post type (e.g., image, video, link, text, carousel)

    Possible values:
    sort_bystring · enumOptional

    Field to sort results by. Supports various engagement and performance metrics

    Possible values:
    sort_typestring · enumOptional

    Sort order direction

    Possible values:
    pageintegerOptional

    Page number for pagination (0-based indexing). Each page contains 10 posts

    member_idstringOptional

    Filter posts by specific workspace member/user ID who created or manages the posts

    Header parameters
    Publer-Workspace-IdstringRequired

    ID of the workspace to retrieve insights from

    Responses
    200

    Post insights data with analytics metrics and pagination information

    application/json
    401

    Unauthorized

    application/json
    403

    Permission denied - requires analytics access or paying subscription

    application/json
    get
    /analytics/{account_id}/post_insights

    List Posts

    get

    Retrieves a list of posts based on the specified filters.

    Authorizations
    AuthorizationstringRequired

    API key authentication. Format: "Bearer-API YOUR_API_KEY"

    Query parameters
    statestring · enumOptional

    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

    Possible values:
    fromstring · dateOptional

    Filter posts scheduled/published after this date

    • Example: 2025-05-15

    Required if to is provided

    tostring · dateOptional

    Filter posts scheduled/published before this date

    • Example: 2025-05-15

    Required if from is provided

    pageintegerOptional

    Page number for pagination

    account_idsstring[]Optional

    Filter posts by multiple account IDs

    querystringOptional

    Search query to filter posts by content

    postTypestring · enumOptional

    Filter by post type

    Available options:

    status, link, photo, gif, video, reel, story, short, poll, document, carousel, article

    Possible values:
    member_idstringOptional

    Filter posts by team member ID

    Header parameters
    Publer-Workspace-IdstringRequired

    ID of the workspace to retrieve posts from

    Responses
    200

    Successful operation

    application/json
    401

    Unauthorized

    application/json
    403

    Permission denied or missing required scope

    application/json
    get
    /posts

    Extract Link Metadata

    post

    Extracts metadata from a URL including title, description, images, and more. Useful for previewing links before creating a post.

    Authorizations
    AuthorizationstringRequired

    API key authentication. Format: "Bearer-API YOUR_API_KEY"

    Body
    urlstringRequired

    The URL to extract metadata from

    Responses
    200

    Successful operation

    application/json
    401

    Unauthorized

    application/json
    422

    Unprocessable Entity - Invalid URL

    application/json
    post
    /posts/links

    Upload a media file directly

    post

    Upload a media file (image, video, or document) to be used in social media posts

    Authorizations
    AuthorizationstringRequired

    API key authentication. Format: "Bearer-API YOUR_API_KEY"

    Header parameters
    Publer-Workspace-IdstringRequired

    ID of the workspace to upload media

    Body
    filestringRequired
    direct_uploadbooleanOptional

    Whether to upload directly to our S3 cloud (slower, but required if you need the final media URL)

    Default: false
    in_librarybooleanOptional

    Whether to save to media library

    Default: false
    Responses
    200

    Media file uploaded successfully

    application/json
    400

    Invalid request parameters

    application/json
    401

    Unauthorized

    application/json
    413

    Permission denied or missing required scope

    application/json
    post
    /media

    Upload media from URL

    post

    Upload media files by providing URLs

    Authorizations
    AuthorizationstringRequired

    API key authentication. Format: "Bearer-API YOUR_API_KEY"

    Header parameters
    Publer-Workspace-IdstringRequired

    ID of the workspace to upload media

    Body
    typestring · enumRequired

    Upload type

    Example: singlePossible values:
    direct_uploadbooleanOptional

    Whether to upload directly to our S3 cloud (slower, but required if you need the final media URL)

    Default: false
    in_librarybooleanOptional

    Whether to save to media library

    Default: false
    Responses
    200

    Media upload job created successfully

    application/json
    400

    Invalid request parameters

    application/json
    401

    Unauthorized

    application/json
    403

    Permission denied or missing required scope

    application/json
    post
    /media/from-url

    Get job status

    get

    Check the status of an asynchronous job, including URL media uploads

    Authorizations
    AuthorizationstringRequired

    API key authentication. Format: "Bearer-API YOUR_API_KEY"

    Path parameters
    job_idstringRequired

    ID of the job to check

    Header parameters
    Publer-Workspace-IdstringRequired

    ID of the workspace to retrieve posts from

    Responses
    200

    Job status retrieved successfully

    application/json
    401

    Unauthorized

    application/json
    403

    Permission denied or missing required scope

    application/json
    get
    /job_status/{job_id}

    Schedule posts

    post

    Schedule one or more posts for publishing. Supports immediate publishing, scheduled publishing, auto-scheduling, recurring posts, and more.

    Authorizations
    AuthorizationstringRequired

    API key authentication. Format: "Bearer-API YOUR_API_KEY"

    Header parameters
    Publer-Workspace-IdstringRequired

    ID of the workspace to schedule posts in

    Body
    Responses
    200

    Posts scheduled successfully

    application/json
    400

    Invalid scheduling parameters

    application/json
    401

    Unauthorized

    application/json
    403

    Permission denied or missing required scope

    application/json
    post
    /posts/schedule

    Create post

    post

    Creates a new social media post. Can be scheduled for immediate publishing, future publishing, or saved as a draft.

    Authorizations
    AuthorizationstringRequired

    API key authentication. Format: "Bearer-API YOUR_API_KEY"

    Header parameters
    Publer-Workspace-IdstringRequired

    ID of the workspace to create post in

    Body
    Responses
    200

    Post creation job initiated

    application/json
    400

    Invalid post data

    application/json
    401

    Unauthorized

    application/json
    403

    Permission denied or missing required scope

    application/json
    post
    /posts/schedule/publish

    Get job status

    get

    Check the status of an asynchronous job, including URL media uploads

    Authorizations
    AuthorizationstringRequired

    API key authentication. Format: "Bearer-API YOUR_API_KEY"

    Path parameters
    job_idstringRequired

    ID of the job to check

    Header parameters
    Publer-Workspace-IdstringRequired

    ID of the workspace to retrieve posts from

    Responses
    200

    Job status retrieved successfully

    application/json
    401

    Unauthorized

    application/json
    403

    Permission denied or missing required scope

    application/json
    get
    /job_status/{job_id}

    Get Hashtag Insights

    get

    Retrieves comprehensive analytics data for hashtags used in published posts. Provides metrics like reach, engagement, likes, comments, shares, and video views for each hashtag, along with recent posts using each hashtag and hashtag performance scores.

    Authorizations
    Path parameters
    account_idstringOptional

    Filter hashtags for a specific social media account ID. If omitted, includes all workspace accounts

    Query parameters
    fromstring · dateOptional

    Start date for hashtag insights data range (YYYY-MM-DD format). Filters posts scheduled on or after this date

    Example: {"value":"2024-01-01"}
    tostring · dateOptional

    End date for hashtag insights data range (YYYY-MM-DD format). Filters posts scheduled on or before this date

    Example: {"value":"2024-12-31"}
    sort_bystring · enumOptional

    Field to sort hashtag results by. Supports various engagement and performance metrics

    Possible values:
    sort_typestring · enumOptional

    Sort order direction

    Possible values:
    pageintegerOptional

    Page number for pagination (0-based indexing). Each page contains 10 hashtags

    querystringOptional

    Search query to filter hashtags by name using case-insensitive matching

    member_idstringOptional

    Filter hashtags by specific workspace member ID

    Header parameters
    Publer-Workspace-IdstringRequired

    ID of the workspace to retrieve insights from

    Responses
    200

    Hashtag insights data with analytics metrics and pagination information

    application/json
    401

    Unauthorized

    application/json
    403

    Permission denied - requires analytics access or paying subscription

    application/json
    get
    /analytics/{account_id}/hashtag_insights

    Get Hashtag Performing Posts

    get

    Retrieves the top performing posts for a specific hashtag. Returns up to 6 posts that used the hashtag, with comprehensive analytics metrics including engagement, reach, likes, comments, shares, and video views.

    Authorizations
    Path parameters
    account_idstringOptional

    Filter posts for a specific social media account ID. If omitted, includes all workspace accounts

    Query parameters
    hashtagstringRequired

    The hashtag to retrieve performing posts for (with # symbol). This parameter is required to filter posts by the specific hashtag

    Example: {"value":"socialmedia"}
    fromstring · dateOptional

    Start date for posts data range (YYYY-MM-DD format). Filters posts scheduled on or after this date

    Example: {"value":"2024-01-01"}
    tostring · dateOptional

    End date for posts data range (YYYY-MM-DD format). Filters posts scheduled on or before this date

    Example: {"value":"2024-12-31"}
    sort_bystring · enumOptional

    Field to sort post results by. Supports various engagement and performance metrics

    Possible values:
    sort_typestring · enumOptional

    Sort order direction

    Possible values:
    member_idstringOptional

    Filter posts by specific workspace member ID

    querystringOptional

    Search query to filter posts by content text, title, or link information using case-insensitive matching

    Header parameters
    Publer-Workspace-IdstringRequired

    ID of the workspace to retrieve posts from

    Responses
    200

    Hashtag performing posts data with analytics metrics

    application/json
    401

    Unauthorized

    application/json
    403

    Permission denied - requires analytics access or paying subscription

    application/json
    get
    /analytics/{account_id}/hashtag_performing_posts
    {
      "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: */*