Delete an Asset

title: Delete an Asset

Delete an Asset

This endpoint allows you to delete an asset from your project. By default, assets are soft-deleted, but you can also permanently delete them.

Endpoint

[DELETE]

/files/{identifier}

Permissions

This endpoint requires a token with the delete ability.

Path Parameters

NameRequiredDescription
identifierYesThe ID or UUID of the asset you want to delete.

Query Parameters

NameRequiredDescription
forceNoIf set to true or 1, the asset will be permanently deleted.

Headers

NameRequiredDescription
AcceptYesSpecifies the response content type. Must be application/json.
AuthorizationYesRequired for private projects. Must be a Bearer token with delete scope.
project-idYesThe unique identifier for the project.

Soft Deleting an Asset

To soft-delete an asset, make a DELETE request without the force parameter.

Example Request

import { createClient } from '@elmapicms/js-sdk';
 
const client = createClient(
  'https://your-domain.com/api',
  'YOUR_API_TOKEN',
  'YOUR_PROJECT_UUID'
);
 
// Soft delete (move to trash)
await client.deleteAsset('ASSET_UUID_OR_ID');
 
// Permanently delete (irreversible)
await client.deleteAsset('ASSET_UUID_OR_ID', true);
// Soft delete (default)
axios.delete('https://your-domain.com/api/files/ASSET_UUID_OR_ID', {
  headers: {
    'Accept': 'application/json',
    'Authorization': 'Bearer YOUR_API_TOKEN', // Required - must have 'delete' ability
    'project-id': 'YOUR_PROJECT_UUID'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error('Error:', error.response?.data || error.message);
});
use Illuminate\Support\Facades\Http;
 
$response = Http::withHeaders([
    'Accept' => 'application/json',
    'project-id' => 'YOUR_PROJECT_UUID',
    'Authorization' => 'Bearer YOUR_API_TOKEN',
])->delete('https://your-domain.com/api/files/ASSET_UUID_OR_ID');
 
dump($response->json());
import React from 'react';
 
function DeleteAssetButton({ assetIdentifier }) {
  const handleDelete = async () => {
    if (!window.confirm("Are you sure you want to delete this asset?")) return;
 
    try {
      const response = await fetch(`https://your-domain.com/api/files/${assetIdentifier}`, {
        method: 'DELETE',
        headers: {
          'Accept': 'application/json',
          'Authorization': 'Bearer YOUR_API_TOKEN', // Required - must have 'delete' ability
          'project-id': 'YOUR_PROJECT_UUID'
        }
      });
 
      if (!response.ok) {
        const errorData = await response.json();
        throw new Error(errorData.message || 'Delete failed');
      }
      const data = await response.json();
      console.log(data.message);
      // Update UI state
    } catch (error) {
      console.error('Failed to delete asset:', error);
    }
  };
 
  return <button onClick={handleDelete}>Delete Asset</button>;
}
<template>
  <button @click="deleteAsset">Delete Asset</button>
</template>
 
<script setup>
import { defineProps } from 'vue';
 
const props = defineProps({
  assetIdentifier: { type: String, required: true }
});
 
const deleteAsset = async () => {
  if (!window.confirm("Are you sure you want to delete this asset?")) return;
 
  try {
    const response = await fetch(`https://your-domain.com/api/files/${props.assetIdentifier}`, {
      method: 'DELETE',
      headers: {
        'Accept': 'application/json',
        'Authorization': 'Bearer YOUR_API_TOKEN', // Required - must have 'delete' ability
        'project-id': 'YOUR_PROJECT_UUID'
      }
    });
 
    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(errorData.message || 'Delete failed');
    }
    const data = await response.json();
    console.log(data.message);
    // Update UI state
  } catch (error) {
    console.error('Failed to delete asset:', error);
  }
};
</script>
curl -X DELETE "https://your-domain.com/api/files/ASSET_UUID_OR_ID" \
     -H "Accept: application/json" \
     -H "project-id: YOUR_PROJECT_UUID" \
     -H "Authorization: Bearer YOUR_API_TOKEN"

Example Response

A successful soft deletion will return a 200 OK status with a confirmation message.

{
    "success": true,
    "message": "Asset \"your-file-name.jpg\" deleted successfully"
}

Permanently Deleting an Asset

To permanently delete an asset, include the force=true query parameter. This action cannot be undone.

Example Request

import { createClient } from '@elmapicms/js-sdk';
 
const client = createClient(
  'https://your-domain.com/api',
  'YOUR_API_TOKEN',
  'YOUR_PROJECT_UUID'
);
 
// Permanently delete (irreversible)
await client.deleteAsset('ASSET_UUID_OR_ID', true);
axios.delete('https://your-domain.com/api/files/ASSET_UUID_OR_ID?force=true', {
  headers: {
    'Accept': 'application/json',
    'Authorization': 'Bearer YOUR_API_TOKEN', // Required - must have 'delete' ability
    'project-id': 'YOUR_PROJECT_UUID'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error('Error:', error.response?.data || error.message);
});
use Illuminate\Support\Facades\Http;
 
$response = Http::withHeaders([
    'Accept' => 'application/json',
    'project-id' => 'YOUR_PROJECT_UUID',
    'Authorization' => 'Bearer YOUR_API_TOKEN',
])->delete('https://your-domain.com/api/files/ASSET_UUID_OR_ID?force=true');
 
dump($response->json());
import React from 'react';
 
function DeleteAssetPermanentlyButton({ assetIdentifier }) {
  const handleDelete = async () => {
    if (!window.confirm("Are you sure? This action is permanent.")) return;
 
    try {
      const response = await fetch(`https://your-domain.com/api/files/${assetIdentifier}?force=true`, {
        method: 'DELETE',
        headers: {
          'Accept': 'application/json',
          'Authorization': 'Bearer YOUR_API_TOKEN', // Required - must have 'delete' ability
          'project-id': 'YOUR_PROJECT_UUID'
        }
      });
 
      if (!response.ok) {
        const errorData = await response.json();
        throw new Error(errorData.message || 'Permanent delete failed');
      }
      const data = await response.json();
      console.log(data.message);
      // Update UI state
    } catch (error) {
      console.error('Failed to permanently delete asset:', error);
    }
  };
 
  return <button onClick={handleDelete}>Delete Permanently</button>;
}
<template>
  <button @click="deleteAssetPermanently">Delete Permanently</button>
</template>
 
<script setup>
import { defineProps } from 'vue';
 
const props = defineProps({
  assetIdentifier: { type: String, required: true }
});
 
const deleteAssetPermanently = async () => {
  if (!window.confirm("Are you sure? This action is permanent.")) return;
 
  try {
    const response = await fetch(`https://your-domain.com/api/files/${props.assetIdentifier}?force=true`, {
      method: 'DELETE',
      headers: {
        'Accept': 'application/json',
        'Authorization': 'Bearer YOUR_API_TOKEN', // Required - must have 'delete' ability
        'project-id': 'YOUR_PROJECT_UUID'
      }
    });
 
    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(errorData.message || 'Permanent delete failed');
    }
    const data = await response.json();
    console.log(data.message);
    // Update UI state
  } catch (error) {
    console.error('Failed to permanently delete asset:', error);
  }
};
</script>
curl -X DELETE "https://your-domain.com/api/files/ASSET_UUID_OR_ID?force=true" \
     -H "Accept: application/json" \
     -H "project-id: YOUR_PROJECT_UUID" \
     -H "Authorization: Bearer YOUR_API_TOKEN"

Example Response

A successful permanent deletion will return a 200 OK status.

{
    "success": true,
    "message": "Asset permanently deleted"
}

Error Responses

403: Forbidden

Returned if the API token does not have the delete ability.

{
    "message": "API token doesn't have the right abilities!"
}

404: Not Found

Returned if the asset does not exist.

{
    "error": "Asset not found"
}
PreviousUpload an Asset
NextGetting Help & Support

Search documentation

Find guides and reference pages