---
title: "Update post"
method: PATCH
path: "/v1/posts/{id}"
---

# Update post

`PATCH /v1/posts/{id}`

## Request

- Base URL: `https://postonce.to/api/public`
- URL: `https://postonce.to/api/public/v1/posts/{id}`
- Auth: HTTP bearer

Updates a scheduled post before it runs.

## Path parameters

- `id` string, uuid, required

## Request body

- object
  - `content` string
  - `external_id` string, nullable
  - `media` MediaInput[]
    - `url` string, required: Required absolute HTTP or HTTPS media URL. Surrounding whitespace is trimmed. Invalid URLs reject the entire request with invalid_media; URL contents are not fetched during validation.
    - `type` 'image' | 'video'
    - `width` integer
    - `height` integer
    - `size` integer
    - `duration` number: Video duration in seconds when known.
    - `thumbnail_url` string: Cover image URL for video media (JPEG or PNG, 8 MB or less). It is applied as the video cover on Instagram Reels and Stories, Facebook Reels, and TikTok (inserted as the video's first frame), and is also used in scheduled and published post previews.
  - `publish_at` string, date-time, nullable
  - `targets` PostTargetInput[]
    - `account_id` string, required
    - `content_override` string, nullable
    - `platform_options` object, nullable: Platform-specific settings are mapped explicitly; unknown properties are stored but are not forwarded automatically. For Farcaster, pass { "channel_id": "founders" } or { "reply_to": { "hash": "0x...", "author_fid": 123 } }. To request native AI-content disclosure on TikTok, YouTube, or Instagram, pass { "ai_generated": true }. Facebook Page publishing does not currently expose an equivalent API field. For Reddit, pass { "subreddit": "SideProject", "title": "Launch title", "postType": "self" }. For Snapchat, pass { "placements": ["spotlight", "public_story"], "locale": "en_US" }; placements default to Spotlight. For a TikTok draft upload, pass { "publish_mode": "draft" }; the creator must finish and publish it from their TikTok inbox. To choose a TikTok cover frame instead of a cover image, pass { "video_cover_timestamp_ms": 1500 }. For Vimeo, pass { "title": "Launch video", "privacy_view": "unlisted" }; privacy_view defaults to anybody. Telegram accepts only { "disable_notification", "protect_content", "disable_link_preview" } booleans and rejects other keys.
      - `ai_generated` boolean: Requests the target platform's native AI-generated or synthetic-media disclosure. Supported for TikTok direct videos, YouTube videos, and Instagram media. Facebook Page publishing does not currently expose an equivalent API field.
      - `channel_id` string: Farcaster channel ID for the cast.
      - `video_cover_timestamp_ms` integer: TikTok direct video posts only. Selects the frame at this position, in milliseconds, as the video cover. When set, it takes precedence over media[].thumbnail_url for that TikTok target. Not supported for photo posts or draft uploads.
      - `title` string: Title for platforms that support one. For Vimeo, 1-128 characters; defaults to the first line of the content.
      - `privacy_view` 'anybody' | 'unlisted' | 'nobody' | 'disable': Vimeo only. Who can view the uploaded video.
      - `reply_to` object, nullable: Farcaster parent cast. Both the full cast hash and parent author FID are required.
        - `hash` string, required
        - `author_fid` integer, required
      - `disable_notification` boolean: Telegram only. Sends the channel post silently; subscribers get no notification sound.
      - `protect_content` boolean: Telegram only. Prevents forwarding and saving of the channel post.
      - `disable_link_preview` boolean: Telegram only. Disables the link preview on text posts.

## Response `200`

Scheduled post updated successfully.

- object
  - `data` Post
    - `id` string
    - `content` string
    - `external_id` string, nullable
    - `media` MediaInput[]
      - `url` string, required: Required absolute HTTP or HTTPS media URL. Surrounding whitespace is trimmed. Invalid URLs reject the entire request with invalid_media; URL contents are not fetched during validation.
      - `type` 'image' | 'video'
      - `width` integer
      - `height` integer
      - `size` integer
      - `duration` number: Video duration in seconds when known.
      - `thumbnail_url` string: Cover image URL for video media (JPEG or PNG, 8 MB or less). It is applied as the video cover on Instagram Reels and Stories, Facebook Reels, and TikTok (inserted as the video's first frame), and is also used in scheduled and published post previews.
    - `origin` 'ui' | 'api' | 'workflow', nullable
    - `publish_at` string, date-time, nullable
    - `status` 'queued' | 'scheduled' | 'processing' | 'partial' | 'published' | 'failed' | 'cancelled'
    - `created_at` string, date-time, nullable
    - `targets` PostTarget[]
      - `target_post_id` string
      - `account_id` string, nullable
      - `platform` string, nullable
      - `target_variant` 'spotlight' | 'public_story', nullable: Concrete placement for platforms that fan one account target into multiple publications.
      - `username` string, nullable
      - `status` 'pending' | 'scheduled' | 'processing' | 'submitted' | 'published' | 'failed' | 'skipped' | 'cancelled'
      - `error` string, nullable
      - `platform_post_id` string, nullable
      - `platform_post_url` string, nullable
      - `scheduled_time` string, date-time, nullable

## Other responses

- `400`: Post ID must be a valid UUID.
- `401`: Missing, invalid, revoked, or expired API key.
- `409`: Post can no longer be updated in its current state.

---

[API](https://skmtc.dev/postonce/apis/postonce-public-api.md) · [All operations](https://skmtc.dev/postonce/apis/postonce-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/postonce/apis/postonce-public-api/revisions/ca9dca40a543?raw)