From c88771d7a06592fb030ec9806907b1837a3772f9 Mon Sep 17 00:00:00 2001
From: Claire <claire.github-309c@sitedethib.com>
Date: Tue, 4 Mar 2025 09:47:39 +0100
Subject: [PATCH] Add documentation for Mastodon API version 4 media deletion
 methods (#1605)

* Add documentation for `delete_media` parameter to `DELETE /api/v1/statuses/:id`

* Add documentation for `DELETE /api/v1/media/:id`

* It's actually version 4

* It's actually version 4
---
 content/en/methods/media.md    | 27 ++++++++++++++++++++++++++-
 content/en/methods/statuses.md |  8 +++++++-
 2 files changed, 33 insertions(+), 2 deletions(-)

diff --git a/content/en/methods/media.md b/content/en/methods/media.md
index 80deefbd..8866b2c4 100644
--- a/content/en/methods/media.md
+++ b/content/en/methods/media.md
@@ -261,6 +261,31 @@ There was an error processing the media attachment
 
 ---
 
+## Delete media attachment {#delete}
+
+```http
+DELETE /api/v1/media/:id
+```
+
+Delete a media attachment that is not currently attached to a status.
+
+**Returns:** Empty\
+**OAuth:** User token + `write:media`\
+**Version history:**\
+- 4.4.0 (`mastodon` [API version]({{< relref "entities/Instance#api-versions" >}}) 4) - added
+
+#### Request
+
+##### Path parameters
+
+:id
+: {{<required>}} String. The ID of the MediaAttachment in the database.
+
+##### Headers
+
+Authorization
+: {{<required>}} Provide this header with `Bearer <user_token>` to gain authorized access to this API method.
+
 ## Update media attachment {#update}
 
 ```http
@@ -493,4 +518,4 @@ File or file type is unsupported or invalid
 
 {{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/media_controller.rb" caption="app/controllers/api/v1/media_controller.rb" >}}
 
-{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v2/media_controller.rb" caption="app/controllers/api/v2/media_controller.rb" >}}
\ No newline at end of file
+{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v2/media_controller.rb" caption="app/controllers/api/v2/media_controller.rb" >}}
diff --git a/content/en/methods/statuses.md b/content/en/methods/statuses.md
index c2f17675..22374ec8 100644
--- a/content/en/methods/statuses.md
+++ b/content/en/methods/statuses.md
@@ -377,10 +377,16 @@ Delete one of your own statuses.
 **OAuth:** User token + `write:statuses`\
 **Version history:**\
 0.0.0 - added\
-2.9.0 - return source properties, for use with delete and redraft
+2.9.0 - return source properties, for use with delete and redraft\
+4.4.0 (`mastodon` [API version]({{< relref "entities/Instance#api-versions" >}}) 4) - added `delete_media` optional parameter
 
 #### Request
 
+##### Query parameters
+
+delete_media
+: Boolean. Whether to immediately delete the post's media attachments. If omitted or `false`, media attachments may be kept for approximately 24 hours so they can be re-used in a new post.
+
 ##### Path parameters
 
 :id