Upload an Asset
This endpoint uploads a new file to the project's asset library.
Endpoint
[POST]
/filesPermissions
This endpoint requires a token with the create ability.
Headers
| Name | Required | Description |
|---|---|---|
Accept | Yes | Specifies the response content type. Must be application/json. |
Authorization | Yes | Required. Must be a Bearer token with create scope. |
project-id | Yes | The unique identifier for the project. |
Content-Type | Yes | Must be multipart/form-data. |
Body Parameters
The request body must be sent as multipart/form-data and include the following field:
| Name | Type | Required | Description |
|---|---|---|---|
file | file | Yes | The file to be uploaded. |
Example Requests
import { createClient } from '@elmapicms/js-sdk';
const client = createClient(
'https://your-domain.com/api',
'YOUR_API_TOKEN',
'YOUR_PROJECT_UUID'
);
// Upload a file
const fileInput = document.querySelector('input[type="file"]');
const uploadedAsset = await client.uploadAsset(fileInput.files[0]);
// Upload with metadata
const uploadedAssetWithMetadata = await client.uploadAsset(fileInput.files[0], {
alt: 'Image description',
category: 'blog'
});const fileInput = document.querySelector('input[type="file"]');
const formData = new FormData();
formData.append('file', fileInput.files[0]);
axios.post('https://your-domain.com/api/files', formData, {
headers: {
'Content-Type': 'multipart/form-data',
'Authorization': 'Bearer YOUR_API_TOKEN', // Required - must have 'create' ability
'project-id': 'YOUR_PROJECT_UUID'
}
});use Illuminate\Support\Facades\Http;
use Illuminate\Http\Client\Response;
$response = Http::withToken('YOUR_API_TOKEN')
->withHeaders([
'project-id' => 'YOUR_PROJECT_UUID'
])
->attach('file', file_get_contents('path/to/your/file.jpg'), 'file.jpg')
->post('https://your-domain.com/api/files');import React, { useState } from 'react';
function AssetUploader() {
const [selectedFile, setSelectedFile] = useState(null);
const handleFileChange = (event) => {
setSelectedFile(event.target.files[0]);
};
const handleUpload = async () => {
if (!selectedFile) return;
const formData = new FormData();
formData.append('file', selectedFile);
try {
const response = await fetch('https://your-domain.com/api/files', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_TOKEN', // Required - must have 'create' ability
'project-id': 'YOUR_PROJECT_UUID'
},
body: formData
});
if (!response.ok) {
const errorData = await response.json();
throw new Error(errorData.message || 'Upload failed');
}
const data = await response.json();
console.log('Upload successful:', data);
} catch (error) {
console.error('Upload failed:', error);
}
};
return (
<div>
<input type="file" onChange={handleFileChange} />
<button onClick={handleUpload}>Upload</button>
</div>
);
}<template>
<div>
<input type="file" @change="onFileSelected" />
<button @click="uploadAsset">Upload</button>
</div>
</template>
<script setup>
import { ref } from 'vue';
const selectedFile = ref(null);
const onFileSelected = (event) => {
selectedFile.value = event.target.files[0];
};
const uploadAsset = async () => {
if (!selectedFile.value) return;
const formData = new FormData();
formData.append('file', selectedFile.value);
try {
const response = await fetch('https://your-domain.com/api/files', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_TOKEN', // Required - must have 'create' ability
'project-id': 'YOUR_PROJECT_UUID'
},
body: formData
});
if (!response.ok) {
const errorData = await response.json();
throw new Error(errorData.message || 'Upload failed');
}
const data = await response.json();
console.log('Upload successful:', data);
} catch (error) {
console.error('Upload failed:', error);
}
};
</script>curl -X POST "https://your-domain.com/api/files" \
-H "Content-Type: multipart/form-data" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "project-id: YOUR_PROJECT_UUID" \
-F "file=@/path/to/your/image.jpg"Responses
200: OK
Returns the newly created asset object.
{
"uuid": "...",
"filename": "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 create ability.
{
"message": "API token doesn't have the right abilities!"
}422: Unprocessable Entity
Returned if the file is missing, exceeds the maximum size, or is of an unsupported type.