Delete Media API: Delete a media file
The Delete Media API removes an uploaded asset for good and releases its occupied space in your project storage. Use it when a file is no longer needed and you want it gone from S3 + CDN origin storage, rather than leaving it in place. The operation is identified by the URL returned when the file was uploaded, so keep that value available before you call the endpoint.
Delete a media file
The Delete Media API removes an uploaded asset for good and releases its occupied space in your project storage. Supply the url returned by /media/upload, which must belong to your project. A successful call reports how many bytes were released, so you can confirm the storage effect instead of assuming removal happened. Because removal cannot be undone, resolve the exact publicUrl or CDN URL for the intended file before sending the request, and do not reuse a URL that belongs to another project.
Authorization
Authenticate every request with the accessKey supplied in the x-access-key header. Send the token exactly as the header value, for example x-access-key: <token>, and send the request body as application/json. Check the header name and value as part of the documented authorization contract before investigating the request body or the response.
Request Body
Send an application/json request body containing the required url field. That field holds the address of the asset to remove: either the publicUrl handed back by /media/upload or the equivalent CDN URL for the same asset. It must belong to your project, and its length must be at least 1. The worked example titled Delete a media file with curl shows the complete request, including the DELETE method, the unchanged /v1/media/ path, the x-access-key header, and the JSON body. Before sending, confirm that url is present, non-empty, and copied from the upload result for the file you intend to remove.
Response Body
The response body uses application/json for both documented status codes. A 200 response confirms a successful deletion and reports freedBytes, the number of bytes freed. A 400 response uses a different shape with success and message. The response decision table below distinguishes the two shapes so you can branch on the status code and read the correct fields. Do not read freedBytes from a 400 response, and do not treat the presence of a message field as a successful deletion.
200 application/json
On success, the 200 application/json response contains success as a boolean and freedBytes as a number. Use freedBytes to record how much project storage was freed by removing the file from S3 + CDN origin storage. The successful deletion response example shows the exact field names and types to expect.
400 application/json
A 400 application/json response contains success as a boolean and message as a string. Read message for the error detail returned with that response, and treat the deletion as not confirmed by a 400 response. The error response example shows the exact field names and types; its success value is a retained source placeholder shown for shape only, not an observed runtime value. The documented contract specifies this shape without enumerating every condition that can produce a 400, so handle the status and message generically in your client.
Worked example and validation checklist
Work through a short validation checklist before and after the call. First, confirm the method is DELETE and the path is /v1/media/ with its trailing slash. Second, confirm the x-access-key header carries your token and that Content-Type is application/json. Third, confirm the body contains url as a non-empty string whose value is the publicUrl or CDN URL for a file in your project. After the call, branch on the status code: on 200, record freedBytes; on 400, surface message and do not assume storage was freed. If the URL does not belong to your project, do not substitute another project's URL or retry with a guessed address, because the contract requires a project-owned URL.
| Field | Type | Required | Constraints and accepted values |
|---|---|---|---|
| url | string | Yes | 1 <= length; either the publicUrl handed back by /media/upload or the equivalent CDN URL for the same asset; must belong to your project |
Exact documented input contract; url must belong to your project.
| Status | Content type | Response fields | How to interpret it |
|---|---|---|---|
| 200 | application/json | success: boolean; freedBytes: number | Deletion succeeded; freedBytes reports the number of bytes freed from project storage |
| 400 | application/json | success: boolean; message: string | Deletion was not confirmed; read message for the returned error detail |
Exact documented response shapes; specific 400 conditions are not enumerated in the source contract.
curl -X DELETE "{{API_BASE_URL}}/v1/media/" \
-H "Content-Type: application/json" \
-H "x-access-key: <token>" \
-d '{
"url": "string"
}'{
"success": true,
"freedBytes": 0
}{
"success": true,
"message": "string"
}| Scope | Field | Type | Type reference | Required | Description | Constraints |
|---|---|---|---|---|---|---|
| body#1 | body | object | __0 | Yes | ||
| body#1 | body.url | string | __1 | Yes | The media URL to delete (the publicUrl returned by /media/upload, or its CDN URL). Must belong to your project. | kind: schemaLength; value: 1 <= length |
| response#2 | response | object | __0 | |||
| response#2 | response.success | boolean | __1 | Yes | ||
| response#2 | response.freedBytes | number | __2 | Yes | ||
| response#3 | response | object | __0 | |||
| response#3 | response.success | boolean | __1 | Yes | ||
| response#3 | response.message | string | __2 | Yes |