List Assets
This endpoint retrieves a list of all assets (files) within a project. It supports pagination and filtering.
Endpoint
[GET]
/filesPermissions
This endpoint requires a token with the read ability.
Query Parameters
| Name | Type | Description |
|---|---|---|
paginate | integer | The number of assets per page. If omitted, all assets are returned. |
page | integer | The page number. Only used when paginate is active. Defaults to 1. |
search | string | A search term to filter assets by filename, original filename, or MIME type. |
type | string | Filters by a general file type. Options: image, video, audio, document. |
Headers
| Name | Required | Description |
|---|---|---|
Accept | Yes | Specifies the response content type. Must be application/json. |
Authorization | Yes | Required. Must be a Bearer token with read scope. |
project-id | Yes | The unique identifier for the project. |
Example Requests
https://your-domain.com/api/files?paginate=20&type=imageimport { createClient } from '@elmapicms/js-sdk';
const client = createClient(
'https://your-domain.com/api',
'YOUR_API_TOKEN',
'YOUR_PROJECT_UUID'
);
// List assets with filtering
const assets = await client.getAssets({
paginate: 20,
type: 'image',
search: 'hero'
});axios.get('https://your-domain.com/api/files', {
params: {
paginate: 20,
type: 'image',
search: 'hero'
},
headers: {
'Accept': 'application/json',
'Authorization': 'Bearer YOUR_API_TOKEN', // Required - must have 'read' ability
'project-id': 'YOUR_PROJECT_UUID'
}
});use Illuminate\Support\Facades\Http;
$response = Http::withToken('YOUR_API_TOKEN')->withHeaders([
'Accept' => 'application/json',
'project-id' => 'YOUR_PROJECT_UUID'
])->get("https://your-domain.com/api/files", [
'paginate' => 20,
'type' => 'image',
'search' => 'hero'
]);import React, { useState, useEffect } from 'react';
function AssetList() {
const [assets, setAssets] = useState([]);
useEffect(() => {
const fetchAssets = async () => {
try {
const params = new URLSearchParams({ paginate: 20, type: 'image' });
const response = await fetch(`https://your-domain.com/api/files?${params}`, {
method: 'GET',
headers: {
'Accept': 'application/json',
'Authorization': 'Bearer YOUR_API_TOKEN', // Required - must have 'read' ability
'project-id': 'YOUR_PROJECT_UUID'
}
});
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
const data = await response.json();
setAssets(data.data);
} catch (error) {
console.error('Error fetching assets:', error);
}
};
fetchAssets();
}, []);
return (
<ul>
{assets.map(asset => (
<li key={asset.uuid}>
<img src={asset.thumbnail_url} alt={asset.filename} />
{asset.filename}
</li>
))}
</ul>
);
}<template>
<ul>
<li v-for="asset in assets" :key="asset.uuid">
<img :src="asset.thumbnail_url" :alt="asset.filename" />
{{ asset.filename }}
</li>
</ul>
</template>
<script setup>
import { ref, onMounted } from 'vue';
const assets = ref([]);
onMounted(async () => {
try {
const params = new URLSearchParams({ paginate: 20, type: 'image' });
const response = await fetch(`https://your-domain.com/api/files?${params}`, {
method: 'GET',
headers: {
'Accept': 'application/json',
'Authorization': 'Bearer YOUR_API_TOKEN', // Required - must have 'read' ability
'project-id': 'YOUR_PROJECT_UUID'
}
});
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
const data = await response.json();
assets.value = data.data;
} catch (error) {
console.error('Error fetching assets:', error);
}
});
</script>curl -G "https://your-domain.com/api/files" \
-d "paginate=20" \
-d "type=image" \
-d "search=hero" \
-H "Accept: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "project-id: YOUR_PROJECT_UUID"Responses
200: OK
Returns a list of asset objects. The response will be paginated if the paginate parameter is used.
{
"data": [
{
"uuid": "...",
"filename": "hero-image.jpg",
"mime_type": "image/jpeg",
"size": "1.2 MB",
"url": "https://...",
"thumbnail_url": "https://...",
"metadata": { ... }
}
],
"links": { ... },
"meta": { ... }
}403: Forbidden
Returned if the API token does not have the read ability.
{
"message": "API token doesn't have the right abilities!"
}