Go to website

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

Submit Request  →  Receive Job ID  →  Poll Job Status  →  Processing Complete

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

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

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

  4. Handle results or errors

Common Request Structure

All create requests share this shape:

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

  • bulk: batch container

  • state: how to handle content (see Publishing Methods)

  • posts: array of post definitions

  • networks: per-network content config

  • accounts: target profiles with scheduling overrides

Endpoints

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

Publishing Methods

The state parameter determines how your content will be handled:

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

recurring

Create repeating posts

recurring.repeat, recurring.days_of_week

Content Types

The type parameter specifies the content format:

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

carousel

Multi-image post

text, media array

pdf

PDF document (LinkedIn)

text, media array

Network Providers

Supported platforms and their keys under networks: facebook, instagram, twitter, linkedin, pinterest, youtube, tiktok, google, wordpress, telegram, mastodon, threads, bluesky.

Job Status

Poll your job with:

GET /api/v1/job_status/{job_id}

Response:

{
  "status": "working|completed|failed",
  "payload": { /* results or errors */ }
}

Common Patterns

Network-Specific Content

To customize content for specific platforms:

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

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

"media": [
  {
    "id": "66fba4234e299e531f5dc100",
    "type": "image",
    "alt_text": "Optional accessibility description"
  }
]

Schedule posts

post

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

Authorizations
Header parameters
Publer-Workspace-IdanyRequired

ID of the workspace to schedule posts in

Body
Responses
200
Posts scheduled successfully
application/json
post
POST /api/v1/posts/schedule HTTP/1.1
Host: app.publer.com
Authorization: YOUR_API_KEY
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
      }
    ]
  }
}
{
  "success": true,
  "data": {
    "job_id": "6810dec617eae6d55d7a5e5b"
  }
}

Create post

post

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

Authorizations
Header parameters
Publer-Workspace-IdanyRequired

ID of the workspace to create post in

Body
Responses
200
Post creation job initiated
application/json
post
POST /api/v1/posts/schedule/publish HTTP/1.1
Host: app.publer.com
Authorization: YOUR_API_KEY
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
      }
    ]
  }
}
{
  "success": true,
  "data": {
    "job_id": "6810dec617eae6d55d7a5e5b"
  }
}

Get job status

get

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

Authorizations
Path parameters
job_idanyRequired

ID of the job to check

Header parameters
Publer-Workspace-IdanyRequired

ID of the workspace to retrieve posts from

Responses
200
Job status retrieved successfully
application/json
get
GET /api/v1/job_status/{job_id} HTTP/1.1
Host: app.publer.com
Authorization: YOUR_API_KEY
Accept: */*

{
  "success": true,
  "data": {
    "status": "complete",
    "result": {
      "status": "working",
      "payload": {
        "failures": {
          "error": "Failed to upload media",
          "code": 500
        }
      },
      "plan": {
        "rate": "business",
        "locked": false
      }
    }
  }
}

Next Steps

This overview covers the essential concepts for creating posts with the Publer API. For detailed information about specific features, refer to:

PreviousMediaNextPublishing Methods

Last updated

Was this helpful?