Brightspot CMS Developer Guide

Uploading files in Brightspot Content Management API

This Integrations section, found in the Developer Guide, covers integrations that require developer intervention to turn on. For quick, out-of-the-box integrations offered by Brightspot, see the Integrations section in the Brightspot CMS User Guide.

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.
The elements that get you up and running in a matter of days, from pre-built content types, to modules, to landing pages.

Content types
Landing pages
Everything you need to manage and administer content within Brightspot CMS, including plug-and-play integrations.

Admin configurations
A guide for installing, supporting and administering code on the Brightspot platform, including integrations requiring developer support to use.

Field types
Content modeling
Rich-text elements