Schedule a draft post to publish at a future time

PUT

/posts/{id}/publication-schedule

• Local development behind nginx (port 8088 by default)

Records a standing instruction to publish this draft at scheduled_for, carried out by the scheduled-action engine (ADR 0020) through the same publication core the publish endpoint uses. The row is an ordinary change_state action on the post, created by THIS caller: created_by is the real requesting user, and the identity, capabilities and authorship it publishes as are loaded again when the action fires. A caller who loses the right to publish before then has stopped the scheduled publication too.

Schedule-time gates, in order: the post must be readable (404 otherwise, deleted posts included); the caller must be its author (403); the caller must currently hold posts.publish (403); the post must currently be a draft (409); and scheduled_for must be in the future (400).

ONE PENDING SCHEDULE PER POST. A PUT that finds the caller’s own pending schedule replaces it in the same transaction, so changing the time is one request. Two requests racing for the same post are serialised by the database: exactly one wins and the other answers 409, after which a re-read shows the winner’s schedule.

Timing. The action becomes eligible at scheduled_for and is carried out on the scheduler’s next normal pass, which runs every few minutes. It is not a to-the-second promise.

Authorizations

• cookieAuth
• bearerAuth

Parameters

Path Parameters

id

required

string format: uuid

Request Body ^required

object

scheduled_for

required

Must be in the future.

string format: date-time

Responses

200

The schedule now standing for this post.

An author’s standing instruction to publish one post (#1119, ADR 0020). A narrow view of the scheduled_actions row the instruction lives in: the generic fields (verb, target kind, params) are fixed for this surface and are not repeated.

object

id

required

string format: uuid

post_id

required

string format: uuid

scheduled_for

required

When the post becomes eligible to publish. It is carried out on the scheduler’s next normal pass after this time, not at this exact second.

string format: date-time

state

required

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

string format: date-time

400

Malformed request

object

error

required

Human-readable error summary

string

Example

the request could not be completed

401

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"
}

403

Authenticated but missing required capabilities

object

error

required

Human-readable error summary

string

Example

the request could not be completed

404

Resource not found

object

error

required

Human-readable error summary

string

Example

the request could not be completed

409

The post is already published, or a concurrent request created the post’s pending schedule first. Re-read the status to see what stands.

object

error

required

Human-readable error summary

string

Example

the request could not be completed

500

Unexpected server error

object

error

required

Human-readable error summary

string

Example

the request could not be completed