Skip to content

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.

id
required
string format: uuid

The post’s id.

object
scheduled_for
required

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.

string format: date-time

The new waiting schedule, in state pending.

A post’s publication schedule as these routes return it.

object
id
required

The schedule’s id. A replacement gets a new id.

string format: uuid
post_id
required

The post this schedule publishes.

string format: uuid
scheduled_for
required

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.

string format: date-time
state
required

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.

string
Allowed values: pending done cancelled failed
created_by
required

The author who scheduled it; always the requesting user.

integer format: int64
created_at
required

When the schedule was saved.

string format: date-time

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed

The 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
error
required

Human-readable error summary

string
Example
the request could not be completed

Unexpected server error

object
error
required

Human-readable error summary

string
Example
the request could not be completed