Get an Asset by Name

Get an Asset by Name

This endpoint retrieves a single asset by its exact original filename. Note that if multiple files have the same name, this will only return the first one found. For unique retrieval, using the ID or UUID is recommended.

Endpoint

[GET]

/files/name/{filename}

Permissions

This endpoint requires a token with the read ability.

Path Parameters

NameRequiredDescription
filenameYesThe exact original filename of the asset.

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/name/{filename}
import { createClient } from '@elmapicms/js-sdk';
 
const client = createClient(
  'https://your-domain.com/api',
  'YOUR_API_TOKEN',
  'YOUR_PROJECT_UUID'
);
 
// Get asset by filename
const asset = await client.getAssetByFilename('hero-image.jpg');
const filename = 'hero-image.jpg';
 
axios.get(`https://your-domain.com/api/files/name/${filename}`, {
    headers: {
        'Accept': 'application/json',
        'Authorization': 'Bearer YOUR_API_TOKEN', // Required - must have 'read' ability
        'project-id': 'YOUR_PROJECT_UUID'
    }
});
use Illuminate\Support\Facades\Http;
 
$filename = 'hero-image.jpg';
 
$response = Http::withToken('YOUR_API_TOKEN')->withHeaders([
    'Accept' => 'application/json',
    'project-id' => 'YOUR_PROJECT_UUID'
])->get("https://your-domain.com/api/files/name/{$filename}");
import React, { useState, useEffect } from 'react';
 
function AssetDetailsByName({ filename }) {
  const [asset, setAsset] = useState(null);
 
  useEffect(() => {
    if (!filename) return;
    const fetchAsset = async () => {
      try {
        const response = await fetch(`https://your-domain.com/api/files/name/${filename}`, {
          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();
        setAsset(data.data);
      } catch (error) {
        console.error('Error fetching asset:', error);
      }
    };
    fetchAsset();
  }, [filename]);
 
  if (!asset) return <div>Loading...</div>;
 
  return <img src={asset.url} alt={asset.filename} />;
}
<template>
  <div v-if="asset">
    <img :src="asset.url" :alt="asset.filename" />
  </div>
</template>
 
<script setup>
import { ref, onMounted, defineProps } from 'vue';
 
const props = defineProps({ filename: { type: String, required: true }});
const asset = ref(null);
 
onMounted(async () => {
  try {
    const response = await fetch(`https://your-domain.com/api/files/name/${props.filename}`, {
      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();
    asset.value = data.data;
  } catch (error) {
    console.error('Error fetching asset:', error);
  }
});
</script>
curl "https://your-domain.com/api/files/name/hero-image.jpg" \
     -H "Accept: application/json" \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "project-id: YOUR_PROJECT_UUID"

Responses

200: OK

Returns the full asset object.

{
    "data": {
        "uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "filename": "hero-image.jpg",
        "mime_type": "image/jpeg",
        "size": "1.2 MB",
        "url": "https://...",
        "thumbnail_url": "https://...",
        "metadata": { ... }
    }
}

403: Forbidden

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

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

404: Not Found

Returned if no asset with the given filename is found.

{
    "error": "Asset not found"
}

Search documentation

Find guides and reference pages