Skip to main content
PATCH
/
api
/
partner
/
v1
/
posts
/
{id}
curl --request PATCH \
  --url https://www.genviral.io/api/partner/v1/posts/post_789 \
  --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"
}'

{
  "ok": true,
  "code": 200,
  "message": "Post updated",
  "data": {
    "id": "post_789",
    "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.
​
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.
​
scheduled_at
string
Optional ISO timestamp. Pass null to push the post back into the “publish ASAP” queue (pending).
​
external_id
string
Optional correlation ID override.
​
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.

​
Limits

Same limits as Create Post: caption ≤500; one video (MP4/MOV/M4V/AVI) under 100MB and 15–60s when duration metadata is present (we warn and attempt if duration is missing), or a slideshow of 1–35 JPG/JPEG/PNG images under 5MB each. Music is only supported when targeting TikTok—requests including Instagram/other platforms with music will be rejected. 
curl --request PATCH \
  --url https://www.genviral.io/api/partner/v1/posts/post_789 \
  --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"
}'

{
  "ok": true,
  "code": 200,
  "message": "Post updated",
  "data": {
    "id": "post_789",
    "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 not part of the workspace
  • 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
  • 404 not_found — post ID is outside the workspace scope
  • 500 update_failed — Database update failed unexpectedly