Skip to content

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.

Request body fields for DELETE /v1/media/
FieldTypeRequiredConstraints and accepted values
urlstringYes1 <= 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.

Response decision table
StatusContent typeResponse fieldsHow to interpret it
200application/jsonsuccess: boolean; freedBytes: numberDeletion succeeded; freedBytes reports the number of bytes freed from project storage
400application/jsonsuccess: boolean; message: stringDeletion was not confirmed; read message for the returned error detail

Exact documented response shapes; specific 400 conditions are not enumerated in the source contract.

Delete a media file with curl
curl -X DELETE "{{API_BASE_URL}}/v1/media/" \
  -H "Content-Type: application/json" \
  -H "x-access-key: <token>" \
  -d '{
    "url": "string"
  }'
Successful deletion response example
{
  "success": true,
  "freedBytes": 0
}
Error response example (retained source placeholder, not observed runtime behavior)
{
  "success": true,
  "message": "string"
}
Interface fields
ScopeFieldTypeType referenceRequiredDescriptionConstraints
body#1bodyobject__0Yes
body#1body.urlstring__1YesThe 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#2responseobject__0
response#2response.successboolean__1Yes
response#2response.freedBytesnumber__2Yes
response#3responseobject__0
response#3response.successboolean__1Yes
response#3response.messagestring__2Yes