Publish on creation
Set publishNow: true and omit scheduledFor:
Publish something already on the calendar
This bypasses scheduledFor and sends the post now.
Track delivery
Publishing is not always synchronous — media has to be uploaded to the platform
and processed. Poll for the outcome:
When it lands, status is published and permalink points at the live post.
When it fails
A failure sets status: "failed" and puts the reason in errorMessage:
Retry by calling publish again — publishing a failed post re-runs delivery
from the failed state. There is no separate retry endpoint.
Check permalink before retrying. If a post reached the platform but Sapt
failed to record the result, it will be failed with a non-null permalink —
retrying that one double-posts. Fix the underlying cause (usually media that
violates a platform rule) before retrying a genuine failure.
Two publish paths
Which one runs is an implementation detail, but it explains the statuses you’ll
see:
- Async (queued) —
draft → queued → publishing → published. The default
for most publishes.
- Sync fallback —
draft → uploading → published. The request holds until
the platform responds.
Either way, published is the only status that means it is live, and failed
is the only other terminal state.