Schedule a draft post to publish at a future time
PUT /posts/{id}/publication-schedule
Schedules one of your draft posts to be published later. The
schedule is a standing instruction: once scheduled_for has passed,
a background job publishes the post as you. It applies the publish
checks for read access, authorship and the workflow move at that
moment, but it isn’t a signed-in request: it doesn’t need an active
session or token, and it doesn’t check your account’s status.
You need to be signed in. The checks run in this order: the post
must be one you can read (404 otherwise, deleted posts included);
you must be its author (403; moderators can’t schedule other
people’s posts); you must hold posts.publish or system.admin
granted globally (403); the post must still be a draft (409); and
scheduled_for must be later than the database’s current time
(400). A body that isn’t valid JSON is refused with 400 before any
of these checks, even before sign-in.
A post can have only one waiting schedule set through these routes;
other scheduled actions on the same post don’t count toward that.
Sending a new time replaces yours: the old schedule is cancelled and
a new one, with its own id, is saved in the same transaction, so if
saving fails, the old one stays. When two requests for the same post
overlap, either both succeed and the later one stands, or one of
them gets 409; read the schedule again to see which one stands.
Scheduling doesn’t change the post or its updated_at.
A background job normally checks for due schedules about every five minutes, but that isn’t a deadline: a backlog, a failed job run or a server that was down or busy can delay it. When it runs, the post is published only if the publish checks pass then, and the run itself can fail. If the post is already published, it’s left as it is; if you published and then unpublished it, it can be published again, under the same checks. If the post is deleted when the schedule runs, the schedule fails; a post restored before then goes through the same checks. The checks here run before the schedule is saved, so a post published in the meantime can still get a schedule; when it runs, a post that’s still published is left as it is, and one that has been unpublished can be published again if the checks pass then.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The post’s id.
Request Body required
Section titled “Request Body required ”object
When to publish: a date-time with a time zone offset, such as 2026-12-01T09:00:00Z. It must be later than the database’s current time when the request is handled, and it’s stored to the microsecond. A missing or null value is refused with 400.
Responses
Section titled “ Responses ”The new waiting schedule, in state pending.
A post’s publication schedule as these routes return it.
object
The schedule’s id. A replacement gets a new id.
The post this schedule publishes.
When the post becomes due to publish. A background job normally checks for due schedules about every five minutes, so the post is published some time after this, if the publish checks pass then; there’s no deadline.
pending while the schedule is marked as waiting, which doesn’t by itself mean the post is still unpublished; the cancel route returns cancelled. These routes never return done or failed: a schedule marked as finished is no longer shown here.
The author who scheduled it; always the requesting user.
When the schedule was saved.
Malformed request
object
Human-readable error summary
Example
the request could not be completedAuthentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}Authenticated but missing required capabilities
object
Human-readable error summary
Example
the request could not be completedResource not found
object
Human-readable error summary
Example
the request could not be completedThe post is already published, or another request for the same post saved its schedule first. Read the schedule again to see which one stands.
object
Human-readable error summary
Example
the request could not be completedUnexpected server error
object
Human-readable error summary
Example
the request could not be completed