Brightspot CMS Developer Guide
Brightspot CMS Developer Guide
Developer guide
Content Management API

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.
Our robust, flexible Design System provides hundreds of pre-built components you can use to build the presentation layer of your dreams.

Asset types
Module types
Page types
Brightspot is packaged with content types that get you up and running in a matter of days, including assets, modules and landing pages.

Content types
Landing pages
Everything you need to know when creating, managing, and administering content within Brightspot CMS.

Admin configurations
A guide for installing, supporting, extending, modifying and administering code on the Brightspot platform.

Field types
Content modeling
Rich-text elements
A guide to configuring Brightspot's library of integrations, including pre-built options and developer-configured extensions.

Google Analytics
Apple News