Brightspot CMS Developer Guide

Uploading files in Brightspot Content Management API

This guide will explain how to upload files to Brightspot records via CMA GraphQL mutation APIs.

Prerequisites for uploading a file
For endpoint configuration, see Custom Content Management API development and Hello Content Management API.

Introduction to uploading a file
Being that the official GraphQL spec does not currently support upload mutations, the CMA implements a popular community extension to the specification: GraphQL multipart request specification.

Background to uploading a file
Consider the following Image content class that will store our file and be configured as a mutable entry field on our endpoint:


import com.psddev.cms.db.Content;
import com.psddev.dari.util.StorageItem;

public class Image extends Content {

    private StorageItem file;

    public StorageItem getFile() {
        return file;

    public void setFile(StorageItem file) {
        this.file = file;

Example of uploading a file

<html lang="en">
        <title>CMA StorageItem Upload Example</title>
        <input type="file" id="file-selector">
            (() => {
                const fileSelector = document.getElementById('file-selector');
                fileSelector.addEventListener('change', (event) => {
                    const file =[0];
                    const query = 'mutation MyMutation($file: Upload!) { com_company_ImageSave( diffs: [{ ' +
                        'com_company_ImageDiff: { file: { file: $file } } }] ) { file {  path  } }}'
                    const variables = { file: null }
                    const operations = { query, variables }
                    const map = { 0: ['variables.file'] }

                    const formData = new FormData();
                    formData.append('operations', JSON.stringify(operations))
                    formData.append('map', JSON.stringify(map))
                    formData.append('0', file,

                    fetch('<API_ENDPOINT_URL>', {
                        method: 'POST',
                        headers: {
                            'x-api-key': '<API_KEY>'
                        body: formData,
                    .then(response => response.json())
                    .then(responseData => {
                        console.log('Success:', responseData);
                        document.body.innerHTML = '<div>Upload Successful!</div>'
                    .catch((error) => {
                        console.error('Error:', error);

Previous Topic
Creating and updating records in Brightspot Content Management API
Next Topic
Custom Content Management API development
Was this topic helpful?
Thanks for your feedback.