List Assets

List Assets

This endpoint retrieves a list of all assets (files) within a project. It supports pagination and filtering.

Endpoint

[GET]

/files

Permissions

This endpoint requires a token with the read ability.

Query Parameters

NameTypeDescription
paginateintegerThe number of assets per page. If omitted, all assets are returned.
pageintegerThe page number. Only used when paginate is active. Defaults to 1.
searchstringA search term to filter assets by filename, original filename, or MIME type.
typestringFilters by a general file type. Options: image, video, audio, document.

Headers

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

Example Requests

https://your-domain.com/api/files?paginate=20&type=image
import { 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!"
}

Search documentation

Find guides and reference pages