Skip to main content
PATCH
/
api
/
partner
/
v1
/
posts
/
{postId}
curl --request PATCH \
  --url https://www.genviral.io/api/partner/v1/posts/11111111-1111-1111-1111-111111111111 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "caption": "Updated caption",
  "media": null,
  "music_url": null,
  "scheduled_at": "2025-03-01T17:00:00Z"
}'

{
  "ok": true,
  "code": 200,
  "message": "Post updated",
  "data": {
    "id": "11111111-1111-1111-1111-111111111111",
    "status": "scheduled",
    "scheduled_at": "2025-03-01T17:00:00Z",
    "warnings": [
      {
        "field": "media",
        "message": "Video size metadata is missing",
        "code": "VIDEO_METADATA_MISSING"
      }
    ]
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.genviral.io/llms.txt

Use this file to discover all available pages before exploring further.

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

​
id
string
required
The ID of the post to update.

​
Body Parameters

​
caption
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.
​
media
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.
​
accounts
array
Optional list of account objects (max 10): [{ "id": "<uuid-from-/accounts>" }]. Replaces the previous targeting list completely.
​
settings
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, not the dashboard settings_schema from GET /accounts — composer field names such as coverUrl are rejected by the Partner API. 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.
​
tiktok
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.
​
pinterest
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.
​
scheduled_at
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.
​
external_id
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.
​
music_url
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. 
curl --request PATCH \
  --url https://www.genviral.io/api/partner/v1/posts/11111111-1111-1111-1111-111111111111 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "caption": "Updated caption",
  "media": null,
  "music_url": null,
  "scheduled_at": "2025-03-01T17:00:00Z"
}'

{
  "ok": true,
  "code": 200,
  "message": "Post updated",
  "data": {
    "id": "11111111-1111-1111-1111-111111111111",
    "status": "scheduled",
    "scheduled_at": "2025-03-01T17:00:00Z",
    "warnings": [
      {
        "field": "media",
        "message": "Video size metadata is missing",
        "code": "VIDEO_METADATA_MISSING"
      }
    ]
  }
}
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