Update Post

Update a scheduled or pending post

PATCH /api/partner/v1/posts/{id}

cURL

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": {
    "type": "slideshow",
    "urls": [
      "https://cdn.genviral.com/reveal-1.jpg",
      "https://cdn.genviral.com/reveal-2.jpg"
    ]
  },
  "music_url": null,
  "scheduled_at": "2025-03-01T17:00:00Z"
}'

Response

{
  "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 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

Optional replacement media payload. Follows the same structure as Create Post.

accounts · array

Optional list of account IDs (max 10). Replaces the previous targeting list completely.

tiktok · object

Optional TikTok settings update.

Supported only when every targeted account is a TikTok BYO account.

Show TikTok Settings

title · string

Optional TikTok title override. Video posts: max 2,200 UTF-16 runes. Photo/slideshow posts: max 90 UTF-16 runes.

description · string

Optional TikTok description override. Photo/slideshow posts: max 4,000 UTF-16 runes. For video posts, Genviral keeps this field for compatibility and uses it as a fallback source when deriving the TikTok title if title is blank.

post_mode · string

DIRECT_POST or MEDIA_UPLOAD (uploads to TikTok inbox/drafts).

privacy_level · string

Optional privacy level (PUBLIC_TO_EVERYONE, MUTUAL_FOLLOW_FRIENDS, FOLLOWER_OF_CREATOR, SELF_ONLY).

disable_comment · boolean

Optional comment toggle.

disable_duet · boolean

Optional duet toggle (video posts).

disable_stitch · boolean

Optional stitch toggle (video posts).

video_cover_timestamp_ms · integer

Optional video cover frame offset in milliseconds (video posts, DIRECT_POST only). TikTok uses this frame as the video thumbnail.

user_consent · boolean

Optional TikTok policy consent flag.

is_commercial · boolean

Optional commercial-content flag.

is_your_brand · boolean

Optional branded-content flag for own brand.

is_branded_content · boolean

Optional branded-content flag for third-party promotion.

auto_add_music · boolean

Optional TikTok auto-music toggle (photo posts).

Pass null to clear stored TikTok settings from the post.

pinterest · object

Optional Pinterest settings update.

Supported only when at least one targeted account is a Pinterest account.

Show Pinterest Settings

board_id · string

Optional Pinterest board ID (max 128 chars).

title · string

Optional Pinterest pin title override (max 100 chars).

link · string

Optional destination URL (max 2,048 chars).

tags · string[]

Optional Pinterest topic tags (up to 30). Multi-word tags are supported. Genviral appends these tags to the Pinterest description, so caption + appended tags must still fit Pinterest’s 800-character description limit.

Pass null to clear stored Pinterest settings from the post.

tiktok and pinterest updates are mutually exclusive in one request. Include only the platform-specific object that matches your targeted accounts. Other platform-specific objects (for example facebook, instagram, linkedin, or youtube settings) are rejected with 422 invalid_payload.

scheduled_at · string

Optional ISO timestamp. Pass null to push the post back into the “publish ASAP” queue (pending).

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.
• 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.

See the Create Post platform matrix for the current per-platform mapping details and source gaps.

cURL

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": {
    "type": "slideshow",
    "urls": [
      "https://cdn.genviral.com/reveal-1.jpg",
      "https://cdn.genviral.com/reveal-2.jpg"
    ]
  },
  "music_url": null,
  "scheduled_at": "2025-03-01T17:00:00Z"
}'

Response

{
  "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
• 404 not_found - post ID is outside the authenticated key scope
• 500 update_failed - Database update failed unexpectedly