Skip to main content
PATCH
Update the caption, media, accounts, schedule, or external metadata for a scheduled/pending post.
Only posts in draft, pending, scheduled, retry, or failed status can be edited. Posted, partial, or canceled posts are immutable.

​
Path Parameters

​
string
required
The ID of the post to update.

​
Body Parameters

​
string
Optional replacement caption. At least one field in the body is required; empty payloads are rejected with 422 invalid_payload.
Target-specific limit. Hosted Accounts targets cap captions at 500 characters. BYO caps follow the selected platform and media type: Facebook 63,206; Instagram 2,200; TikTok 2,200 for video captions / 4,000 for photo-post descriptions; LinkedIn 3,000; Pinterest 800; YouTube 5,000 bytes.
​
object | null
Optional replacement media payload. Follows the same structure as Create Post. Pass null to clear media and make the post text-only. Text-only updates fail when any selected account requires media.
​
array
Optional list of account objects (max 10): [{ "id": "<uuid-from-/accounts>" }]. Replaces the previous targeting list completely.
​
object
Optional canonical provider settings update keyed by provider/platform. Unknown provider keys fail closed with 422 invalid_payload. Partial settings.<provider> patches merge with stored values (they do not replace the whole provider block). Use the field tables in Create Post or the public settings_schema from GET /accounts; its field names match this Partner API payload. For YouTube, send settings.youtube.title to set the video title explicitly; if omitted, Genviral derives the title from the first non-empty caption line.
​
object | null
Optional TikTok settings update. Send TikTok-specific fields here (top-level), not under settings.tiktok. Pass null to clear stored TikTok settings from the post.
Supported only when every targeted account is a TikTok BYO account.
Pass null to clear stored TikTok settings from the post.
​
object | null
Optional Pinterest settings update. Send Pinterest-specific fields here (top-level), not under settings.pinterest. Pass null to clear stored Pinterest settings from the post.
Supported only when at least one targeted account is a Pinterest account.
Pass null to clear stored Pinterest settings from the post.
TikTok and Pinterest use top-level tiktok / pinterest on create and update (same as Create Post). Other providers use settings.<provider>. Only include settings for providers present in the selected accounts.
​
string | null
Optional ISO 8601 datetime with timezone offset. Pass null to push the post back into the immediate publish queue (status: pending). For true scheduled times, the value must be at least 2 minutes in the future.
​
string
Not mutable after creation. Partner API treats external_id as the create-time idempotency key, so PATCH requests that try to change it return 409 external_id_immutable.
​
string
Optional TikTok post URL for background music (e.g., https://www.tiktok.com/@genviral/video/1234567890). Pass null to remove existing music without changing media. This field is TikTok-only. Instagram’s official publishing API does not support music/sound selection for carousels or Reels, so update requests that include Instagram accounts with music_url will be rejected.

​
Limits

  • Caption: enforced against the targeted accounts. Hosted Accounts targets stay at 500 characters. BYO caps follow platform limits: Facebook 63,206; Instagram 2,200; TikTok 2,200 for video captions and 4,000 for photo-post descriptions; LinkedIn 3,000; Pinterest 800; YouTube 5,000 bytes.
  • Text-only: set media to null or omit media while updating other fields; every selected account must advertise text_only in /accounts capabilities.
  • Video: MP4/MOV/M4V/AVI, under 100MB. If duration metadata is present, we enforce 15–60 seconds; when duration is missing we proceed with a warning. ~9:16 aspect recommended.
  • Slideshow: 1–35 images, JPG/JPEG/PNG, each under 5MB. ~9:16 aspect recommended.
  • Music: TikTok-only. Instagram’s official API does not support music/sound selection for carousel posts or Reels, so requests with music_url are rejected when any Instagram account is selected.
  • TikTok settings: supported only when all selected accounts are TikTok BYO accounts.
  • tiktok.post_mode = MEDIA_UPLOAD: supported only for media.type = slideshow (photo posts).
  • tiktok.video_cover_timestamp_ms: supported for video DIRECT_POST requests.
  • Pinterest settings: supported only when at least one selected account is Pinterest.
  • pinterest.tags: up to 30 tags, each 1–100 characters (spaces allowed). Tags are appended to the final Pinterest description, which still must fit 800 characters.
  • Provider settings: send canonical settings under settings.<provider>. Unknown provider keys are rejected with 422 invalid_payload.
See Create Post provider settings for the current per-platform field reference.
Update responses can include warnings about missing media metadata. They are informational so you can re-upload media before Hosted Accounts reject it.

​
Error Responses

  • 400 invalid_json - body is not valid JSON
  • 422 invalid_payload - no editable fields provided or schema validation failed
  • 400 unknown_accounts - one or more provided accounts are outside the authenticated key scope
  • 400 missing_accounts - resolved account list is empty after validation
  • 400 validation_failed - post is immutable or media/music/caption rules failed
  • 400 invalid_music_url or 400 media_unreachable - TikTok/music URLs failed validation
  • 401 - authentication failed (missing/invalid/revoked token)
  • 402 subscription_required - active Creator/Professional/Business plan required
  • 403 tier_not_allowed - Scheduler tier cannot use Partner API
  • 409 external_id_immutable - PATCH tried to change external_id
  • 403 subscription_required - hosted TikTok posting without an active TikTok virtual subscription
  • 500 update_failed - Database update failed unexpectedly