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_basic (self-hosted wordpress), wordpress_oauth (hosted on 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

BearerApiAuth

AuthorizationstringRequired

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

Header parameters

Publer-Workspace-IdstringRequired

ID of the workspace to schedule posts in

Body

application/json

Responses

200

Posts scheduled successfully

application/json

successbooleanOptional

Whether the job was created successfully

Example: true

400

Invalid scheduling parameters

application/json

401

Unauthorized

application/json

403

Permission denied or missing required scope

application/json

post

/posts/schedule

HTTPcURLJavaScriptPython

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

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

BearerApiAuth

AuthorizationstringRequired

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

Header parameters

Publer-Workspace-IdstringRequired

ID of the workspace to create post in

Body

application/json

Responses

200

Post creation job initiated

application/json

successbooleanOptional

Whether the job was created successfully

Example: true

400

Invalid post data

application/json

401

Unauthorized

application/json

403

Permission denied or missing required scope

application/json

post

/posts/schedule/publish

HTTPcURLJavaScriptPython

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

{
  "success": true,
  "data": {
    "job_id": "6810dec617eae6d55d7a5e5b"
  }
}

Get job status

get

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

Authorizations

BearerApiAuth

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

successbooleanOptional

Whether the request was successful

Example: true

401

Unauthorized

application/json

403

Permission denied or missing required scope

application/json

get

/job_status/{job_id}

HTTPcURLJavaScriptPython

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

• Publishing Methods: Complete documentation of all publishing options

• Content Types: Detailed guide to content formats and requirements

• Media Handling: Information about uploading and managing media

• Network Reference: Platform-specific capabilities and limitations