Images
Detach post media
Removes media from a draft without deleting its library file. On a LinkedIn draft pass imageId to remove one image and keep the others, or nothing to remove all images, the carousel, the video and the PDF. On an X post pass the assetId of the image to remove; the text and the other images stay.
/api/public/posts/:id/mediacurl -X DELETE "https://postiv.ai/api/public/posts/POST_ID/media?assetId=ASSET_ID" \
-H "Authorization: Bearer pk_postiv_..."{
"success": true,
"postId": "post1...",
"status": "draft",
"channel": "x",
"assetId": "ast1...",
"postVersionNumber": 4
}Authorization
Requires an organization API key with the posts:write scope, sent as Authorization: Bearer or x-api-key.
Path parameters
idstringrequiredDraft post id.
Query parameters
assetIdstringX posts only, and required there: the assetId of the image to remove (from GET /api/public/posts/:id tweets or article images, or media.assetId of attach-post-media). Also accepted in a JSON body. A LinkedIn post with assetId returns 400 asset_id_not_supported.
imageIduuidLinkedIn drafts only: the imageId of one image to remove (from post.images of GET /api/public/posts/:id). Also accepted in a JSON body. Omit it to remove all media. 404 image_not_on_post if the image is not on the draft.
Response
The detach result.
successbooleanpostIduuidstatusstringmedianullLinkedIn drafts without imageId: always null.
removedImageId / imageCountmixedLinkedIn drafts with imageId: the removed image and how many images the draft still has.
channel / assetId / removedFrom / postVersionNumbermixedX posts only: the removed asset, where it was used in the post, and the post's new version number.
Errors
| 400 | asset_id_required: an X post can carry several images or videos, so assetId is required / asset_id_not_supported: assetId sent for a LinkedIn post |
| 404 | post_not_found / x_asset_not_in_post: the X post does not use that asset |
| 409 | post_media_locked: the X post is scheduled or published |
Good to know
- MCP twin: detach_post_media.