Drafts, scheduling and publishing
How a post moves from draft to scheduled to published, and how to check the result from the API.
Last checked against the API October 10, 2026 · View as Markdown
Post statuses
| Status | Meaning |
|---|---|
draft | Saved, not scheduled. Nothing publishes until it is scheduled. |
scheduled | Publishes automatically at scheduled_at. |
publishing | Being sent to the platforms right now. |
published | Sent to every platform in platforms. |
failed | At least one platform did not accept the post. Open it in Postprism to see which one and why. |
Draft first, or schedule straight away
Create a post without scheduled_at and it is a draft that waits on the calendar for review. Create it with scheduled_at and it is scheduled immediately. For automations you are still testing, and for anything an AI writes, start with drafts.
Schedule or unschedule a draft
Updating scheduled_at alone does not change the status. Send both:
{ "status": "scheduled", "scheduled_at": "2026-10-16T09:30:00Z" }To stop a scheduled post, send { "status": "draft", "scheduled_at": null }. Deleting the post also stops it.
What gets published
- Each platform publishes
platform_content.<platform>.content, followed by that version’shashtags. Set a version for every platform inplatforms; a platform without one fails to publish. - The post’s
mediais attached to every platform. Each network uses what it supports, described in the platform guides. - Only accounts connected in the workspace can publish. Connect accounts in Postprism; the API cannot.
Times and time zones
Send scheduled_at as an ISO 8601 date-time. Use UTC with a Z suffix (2026-10-16T09:30:00Z) or include an offset (2026-10-16T11:30:00+02:00). Times are returned in UTC.
Checking the result
After the scheduled time, read the post with GET /api/v1/posts/{id} and check status and published_at. To find everything that failed, list posts with ?status=failed.