Skip to main content
PublishBuddy supports three publish_type values. Picking the right one depends on the use case.

​
Publish now

Useful for breaking news, manual triggers, or scripts that run on cron and publish immediately.
The handoff to the social network happens asynchronously — status will be publishing for a few seconds, then published.

​
Schedule for a fixed datetime

When you know exactly when a post should go live. Always send publish_at in UTC.
The post is created with status: waiting and publish_at set. PublishBuddy’s workers pick it up at the scheduled minute, transition it to publishing, and push to the network.
Need to publish at a user’s local time? Convert to UTC client-side using the user’s IANA timezone (Australia/Sydney, America/New_York, etc.). The API stores and reasons exclusively in UTC.

​
Editing or cancelling a scheduled post

While the post is still waiting, you can update it (change text, swap media, push the time back) with PUT /posts/{post}, or cancel it entirely with DELETE /posts/{post}. Once the worker picks it up (status → publishing), it’s too late.

​
Queue using timeslots

The most powerful publish type. Every profile has a configurable weekly queue — a set of recurring timeslots like “Tuesday 9am, Thursday 2pm, Saturday 11am”. Posts created with this publish type are slotted into the next available timeslot for the target profile.
The created post has status: waiting, a queue_id, and a publish_at set to the timeslot it was assigned to. If your script bulk-creates 30 queued posts, they’ll spread across the next 30 timeslots in the profile’s queue.
Timeslots are profile-local. Each profile has its own queue. There’s no API endpoint to edit timeslots — they’re configured in the dashboard under Profile → Queue.

​
Reordering inside the queue

You can change the publish order by updating each post’s publish_at (which moves it to a different existing timeslot) via PUT /posts/{post}. The queue editor in the dashboard offers a drag-and-drop UI for the same operation if you want a UI-driven workflow.

​
Bulk scheduling

A common use case: import a CSV of 50 planned posts and schedule them across the next month. The recipe:
  1. Upload each row’s media via the presign → upload → confirm flow (batch up to 10 files per presign/confirm call — see Upload and manage media).
  2. For each row, POST /workspaces/{workspace}/posts with the right publish_type.
  3. Track the returned post.id so you can update or cancel later.
Watch out for the rate limit (throttle:api_1000_per_min on the posts endpoint group — see Rate limits). For most bulk imports, a Promise.allSettled with a concurrency limit of ~20 is comfortable.

​
Status of all scheduled posts

Use the status filter to slice by lifecycle stage (draft, needs_approval, waiting, published, failed). Combine with the from / to query parameters to scope to a date range.

​
Common scheduling gotchas

Almost always caused by an expired profile connection. Check the profile in the dashboard — if it shows “needs reconnection”, the user has to complete the OAuth flow again. After reconnecting, retry the post.
Sending a publish_at value in the past returns 422. If you want to publish immediately, use publish_type: "now" instead.
publish_type: queue_using_timeslots requires the profile to have at least one timeslot defined. If the queue is empty, the create call returns 422. Add timeslots in the dashboard or switch to a fixed datetime.
Because PublishBuddy stores everything in UTC, DST transitions don’t move scheduled posts. A post scheduled for “09:00 UTC” stays at 09:00 UTC even when local time shifts by an hour. If your end users expect “9am local always”, convert from local → UTC at scheduling time and accept that the UTC value will shift by an hour twice a year.