---
updatedAt: 2026-06-22T12:27:52.000Z
agentTools:
  projectIndex: https://partner-docs.gupshup.io/llms.txt
---

# Delete media by media ID

Permanently deletes a media file from WhatsApp servers using the mediaId. Once deleted, the operation cannot be undone.


<Callout icon="📘" theme="info">
  Rate limit: 10 requests per hour
</Callout>

## Request Parameters

<Table align={["left","left","left","left","left","left"]}>
  <thead>
    <tr>
      <th style={{ textAlign: "left" }}>
        Key
      </th>

      <th style={{ textAlign: "left" }}>
        Description
      </th>

      <th style={{ textAlign: "left" }}>
        Value
      </th>

      <th style={{ textAlign: "left" }}>
        Data type
      </th>

      <th style={{ textAlign: "left" }}>
        Required/Optional
      </th>

      <th style={{ textAlign: "left" }}>
        Constraints
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td style={{ textAlign: "left" }}>
        Authorization
      </td>

      <td style={{ textAlign: "left" }}>
        Access Token for the application
      </td>

      <td style={{ textAlign: "left" }}>
        \{\{PARTNER_APP_TOKEN}}
      </td>

      <td style={{ textAlign: "left" }}>
        String
      </td>

      <td style={{ textAlign: "left" }}>
        Required
      </td>

      <td style={{ textAlign: "left" }}>
        Should be a valid Partner App Access Token
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>
        appId
      </td>

      <td style={{ textAlign: "left" }}>
        App ID to fetch the access token
      </td>

      <td style={{ textAlign: "left" }}>
        \{\{APP_ID}}
      </td>

      <td style={{ textAlign: "left" }}>
        String
      </td>

      <td style={{ textAlign: "left" }}>
        Required
      </td>

      <td style={{ textAlign: "left" }}>
        * The Id should be a valid app Id of Gupshup.
        * The App must be associated with the account that owns the PARTNER_APP_TOKEN being used
      </td>
    </tr>

    <tr>
      <td style={{ textAlign: "left" }}>
        mediaId
      </td>

      <td style={{ textAlign: "left" }}>
        Media ID of the media which is being deleted
      </td>

      <td style={{ textAlign: "left" }}>
        \{\{MEDIA_ID}}
      </td>

      <td style={{ textAlign: "left" }}>
        String
      </td>

      <td style={{ textAlign: "left" }}>
        Required
      </td>

      <td style={{ textAlign: "left" }}>
        Valid media ID associated with the given app ID
      </td>
    </tr>
  </tbody>
</Table>

## Sample Request

```curl
curl --location --request DELETE 'https://partner.gupshup.io/partner/app/{{APP_ID}}/media/{{MEDIA_ID}}' \
--header 'Authorization: {{PARTNER_APP_TOKEN}}'
```

## Sample Responses

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th>
        Status Code
      </th>

      <th>
        Response
      </th>

      <th>
        Comments
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        **Success**
      </td>

      <td>

      </td>

      <td>

      </td>
    </tr>

    <tr>
      <td>
        200
      </td>

      <td>
        `{
                    "message": "Media deleted successfully",
                    "status": "success"
                }`
      </td>

      <td>
        Media successfully deleted from WhatsApp servers
      </td>
    </tr>

    <tr>
      <td>
        **Error**
      </td>

      <td>

      </td>

      <td>

      </td>
    </tr>

    <tr>
      <td>
        400
      </td>

      <td>
        `{
                    "message": "Failed to delete media",
                    "status": "error"
                }`
      </td>

      <td>
        Bad Request - Invalid media ID or deletion failed
      </td>
    </tr>

    <tr>
      <td>
        400
      </td>

      <td>
        `{
                    "message": "Delete media operations are temporarily blocked for this app due to previous errors. Please try again later.",
                    "status": "error"
                }`
      </td>

      <td>
        Temporary block due to previous errors
      </td>
    </tr>

    <tr>
      <td>
        500
      </td>

      <td>
        \{

        "status": "error","message": "Internal Server Error"}
      </td>

      <td>
        For any Internal Error
      </td>
    </tr>
  </tbody>
</Table>

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Delete Media by MediaId",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://partner.gupshup.io"
    }
  ],
  "paths": {
    "/partner/app/{appId}/media/{mediaId}": {
      "delete": {
        "tags": [
          "Media Management"
        ],
        "summary": "Delete media by media ID",
        "description": "Permanently deletes a media file from WhatsApp servers using the mediaId. Once deleted, the operation cannot be undone.\n",
        "parameters": [
          {
            "name": "token",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Partner App Access Token. Include as: `Bearer <token>`\n",
            "example": "sk_61b3021c97214370b341f8baaae0xxxx"
          },
          {
            "name": "appId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Unique app identifier",
            "example": "bf9ee64c-3d4d-4ac4-xxxx-732e577007c4"
          },
          {
            "name": "mediaId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Media Identifier which will be deleted",
            "example": 1167129071724006
          }
        ],
        "responses": {
          "200": {
            "description": "Successful deletion",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "Media deleted successfully"
                    },
                    "status": {
                      "type": "string",
                      "example": "success"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request - Invalid ID or blocked delete operation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "Failed to delete media"
                    },
                    "status": {
                      "type": "string",
                      "example": "error"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Invalid or missing token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "Authentication Failed"
                    },
                    "status": {
                      "type": "string",
                      "example": "error"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - No permission to perform delete",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "Access denied"
                    },
                    "status": {
                      "type": "string",
                      "example": "error"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not Found - MediaId not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "Media ID not found or already deleted"
                    },
                    "status": {
                      "type": "string",
                      "example": "error"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests - Rate Limit applied",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "Rate limit exceeded. Try again later."
                    },
                    "status": {
                      "type": "string",
                      "example": "error"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "Internal server error occurred while deleting media"
                    },
                    "status": {
                      "type": "string",
                      "example": "error"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```