> ## Documentation Index
> Fetch the complete documentation index at: https://docs.postonce.to/llms.txt
> Use this file to discover all available pages before exploring further.

# Schedule a post

> Schedule a future post with the PostOnce Public API.

Add `publish_at` to create a scheduled post.

```bash theme={null}
curl -s \
  -H "Authorization: Bearer po_live_xxxxx_xxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: scheduled-launch-001" \
  -X POST https://postonce.to/api/public/v1/posts \
  -d '{
    "content": "Scheduled launch note",
    "publish_at": "2026-04-01T14:00:00.000Z",
    "targets": [
      { "account_id": "account-1" }
    ]
  }'
```

## Supported follow-up actions

* `GET /v1/posts/{id}` to inspect the aggregate scheduled post
* `PATCH /v1/posts/{id}` to update it before it runs
* `POST /v1/posts/{id}/publish` to run it now
* `POST /v1/posts/{id}/cancel` or `DELETE /v1/posts/{id}` to cancel it

## Custom video covers

Set `thumbnail_url` on a video media item to use your own cover image. PostOnce applies it as the cover on Instagram Reels and Stories, Facebook Reels, and TikTok. The same image is used for post previews.

```json theme={null}
{
  "content": "New episode is live",
  "publish_at": "2026-04-01T14:00:00.000Z",
  "media": [
    {
      "url": "https://cdn.example.com/episode.mp4",
      "type": "video",
      "thumbnail_url": "https://cdn.example.com/episode-cover.jpg"
    }
  ],
  "targets": [
    { "account_id": "instagram-account-id" },
    { "account_id": "facebook-account-id" },
    { "account_id": "tiktok-account-id" }
  ]
}
```

* Use a JPEG or PNG of 8 MB or less, at the same aspect ratio as the video.
* TikTok's API has no field for a cover image, so PostOnce inserts the image as the first frame of the video, which TikTok then uses as the cover.
* To use a frame of the video as the TikTok cover instead, set `platform_options.video_cover_timestamp_ms` on the TikTok target. This works for direct video posts only, not photo posts or draft uploads, and it takes precedence over `thumbnail_url` for that target.
* Covers aren't applied to video items inside Instagram carousels.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.