Previews and scheduling

Private preview links

Post responses include previewUrl when a public site URL is available. Your agent can get it from posts.create, posts.get, posts.update, or other post responses. The link points to /preview/<token> on your blog. Anyone with the link can read the latest saved version without signing in, so share it only with reviewers you trust.

The preview shows the current saved tip, even when an older version is live. It sends Cache-Control: private, no-store, max-age=0 and X-Robots-Tag: noindex, nofollow. Archiving makes the link return 404; restoring the post makes the same link work again. Use posts.preview.rotate (posts:update) to issue a new link and invalidate the old one immediately. A preview link is for review, not publication approval by itself.

posts.preview is different: it renders Markdown for an agent and returns an outline and warnings. It does not create a private browser link for unsaved content.

Schedule an approved version

posts.schedule requires posts:publish. Ask the person to approve the exact saved version and UTC time. Send postId, versionNumber (a positive integer), and publishAt (a Unix epoch second that must be in the future — the API rejects past times). This example schedules 2027-01-15 09:00 UTC:

{"postId":"post_...","versionNumber":4,"publishAt":1800003600}

The scheduler runs every minute, so publication should usually follow the target time within about a minute. Later edits do not change the scheduled version. You can reschedule by calling posts.schedule again with another saved version or future time. posts.unschedule cancels a pending or failed schedule. Once a schedule is processing, scheduling returns CONFLICT with “Schedule is already publishing” and unscheduling returns CONFLICT with “Already publishing” — HTTP 409 over REST, an error tool result over MCP (see error shapes).

You cannot schedule an archived post. Archiving the post before the worker publishes it deletes the pending schedule — the activity entry reads as a canceled schedule, not a failed publication. A scheduled version can publish even if a newer draft tip exists. The resulting activity entry reads Published scheduled v4 of <title> · Scheduled by <name> for version 4.

Transient publish failures retry up to three attempts. Billing, version/slug conflicts, missing content, validation, and image/cover errors stop the schedule immediately. A crashed final attempt is also marked failed once its lease expires. Terminal failures appear in Activity and the post’s schedule status; inspect the reason, fix the issue, then reschedule or use posts.unschedule to clear it.

CLI

The CLI accepts an ISO-8601 UTC time ending in Z and sends it as publishAt; the API converts it:

vibecms posts get post_... --json
vibecms posts schedule post_... --version-number 4 --at 2027-01-15T09:00:00Z
vibecms posts unschedule post_...
vibecms posts rotate-preview post_...

The --at time must be in the future or the API rejects the request.