Scheduling

Choose when publishing begins. Follow delivery to its final state.

Schedule a post

Set scheduled_at to an ISO 8601 timestamp between 5 seconds and 1 year in the future. Always include Z or an explicit offset. Omitting the field queues the post immediately.

TypeScript

const scheduledAt = new Date(Date.now() + 60 * 60 * 1000);

const { data: post } = await castrook.posts.create({
  text: 'See you in an hour.',
  account_ids: ['acc_your_account_id'],
  media: { type: 'video', url: 'https://your-cdn.com/clip.mp4' },
  scheduled_at: scheduledAt.toISOString(),
}, { idempotencyKey: 'afternoon-post-v1' });

A scheduled time is when publishing becomes due. Uploading, processing, moderation, platform limits, and temporary outages can delay final visibility.

Post lifecycle

State	Meaning
`scheduled`	Stored until the requested time
`queued`	Ready for dispatch
`publishing`	One or more destinations are processing
`published`	Every destination completed
`partially_failed`	At least one destination failed and another succeeded
`failed`	Delivery failed for every destination
`canceled`	Canceled before delivery began

Inspect targets[] for per-account state. A failed destination does not roll back already-published posts.

Cancel pending work

cURL

curl -X DELETE https://castrook.com/api/v1/posts/pst_your_post_id \
  -H "Authorization: Bearer $CASTROOK_API_KEY"

You can cancel a queued or scheduled post before delivery begins. Canceling is not a social-platform delete operation. Once publishing starts, cancellation can return a conflict.

Change a schedule

Cancel the pending post, then create a new one with the new timestamp and a new idempotency key. The original post remains available in your history.

Keep media available

Use a stable HTTPS media URL that remains available through delivery. Avoid short-lived signed URLs for far-future schedules. Castrook stages eligible TikTok media on temporary storage for delivery; the source must remain available until ingestion.