Upload an Asset

Upload an Asset

This endpoint uploads a new file to the project's asset library.

Endpoint

[POST]

/files

Permissions

This endpoint requires a token with the create ability.

Headers

NameRequiredDescription
AcceptYesSpecifies the response content type. Must be application/json.
AuthorizationYesRequired. Must be a Bearer token with create scope.
project-idYesThe unique identifier for the project.
Content-TypeYesMust be multipart/form-data.

Body Parameters

The request body must be sent as multipart/form-data and include the following field:

NameTypeRequiredDescription
filefileYesThe 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.

Search documentation

Find guides and reference pages