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
| Name | Required | Description |
|---|---|---|
filename | Yes | The exact original filename of the asset. |
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/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"
}