Show examples in:
    Create a new upload

    To upload a new asset to a DatoCMS project you will need to perform three separate HTTP calls. This helps DatoCMS making the uploading process extremely fast, as we don't need to be a middleman between you (the user that wants to upload an asset) and the storage bucket.

    We strongly recommend to use our Javascript client to upload new assets, as it provides helper methods that take care of all the details for you.

    Parameters

    id  string  Optional
    RFC 4122 UUID of upload expressed in URL-safe base64 format
    path  Required  string  Example: "/45/1496845848-digital-cats.jpg"

    Upload path

    copyright  Optional  string, null  Example: "2020 DatoCMS"

    Copyright

    author  Optional  string, null  Example: "Mark Smith"

    Author

    notes  Optional  string, null  Example: "Nyan the cat"

    Notes

    default_field_metadata  Optional  object  Example: {"en":{"title":"this is the default title","alt":"this is the default alternate text","custom_data":{"foo":"bar"},"focal_point":{"x":0.5,"y":0.5}}}

    For each of the project's locales, the default metadata to apply if nothing is specified at record's level.

    tags  Optional  Array<string>  Example: ["cats"]

    Tags

    Returns

    Returns a upload resource object.

    Examples

    The following examples are available:

    Create an upload (in Node.js)

    This example shows how to add assets to the Media Area by uploading both local or remote files:

    Example code:
    import { buildClient } from '@datocms/cma-client-node';
    function handleProgress(info) {
    // info.type can be one of the following:
    //
    // * DOWNLOADING_FILE: client is downloading the asset from the specified URL
    // * REQUESTING_UPLOAD_URL: client is requesting permission to upload the asset to the DatoCMS CDN
    // * UPLOADING_FILE: client is uploading the asset
    // * CREATING_UPLOAD_OBJECT: client is finalizing the creation of the upload resource
    console.log('Phase:', info.type);
    // Payload information depends on the type of notification
    console.log('Details:', info.payload);
    }
    async function run() {
    const client = buildClient({ apiToken: '<YOUR_API_TOKEN>' });
    // Create upload resource from a remote URL
    const upload1 = await client.uploads.createFromUrl({
    // remote URL to upload
    url: 'https://example.com/image.png',
    // if you want, you can specify a different base name for the uploaded file
    filename: 'different-image-name.png',
    // skip the upload and return an existing resource if it's already present in the Media Area:
    skipCreationIfAlreadyExists: true,
    // be notified about the progress of the operation.
    onProgress: handleProgress,
    // specify some additional metadata to the upload resource
    author: 'New author!',
    copyright: 'New copyright',
    });
    // Create upload resource from a local file
    const upload2 = await client.uploads.createFromLocalFile({
    // local path of the file to upload
    localPath: './image.png',
    // if you want, you can specify a different base name for the uploaded file
    filename: 'different-image-name.png',
    // skip the upload and return an existing resource if it's already present in the Media Area:
    skipCreationIfAlreadyExists: true,
    // be notified about the progress of the operation.
    onProgress: handleProgress,
    // specify some additional metadata to the upload resource
    author: 'New author!',
    copyright: 'New copyright',
    default_field_metadata: {
    en: {
    alt: 'New default alt',
    title: 'New default title',
    focal_point: {
    x: 0.3,
    y: 0.6,
    },
    custom_data: {
    watermark: true,
    },
    },
    },
    });
    console.log(upload2);
    }
    run();
    Returned output:
    const result = {
    id: '4124',
    size: 444,
    width: 30,
    height: 30,
    path: '/45/1496845848-different-image-name.png',
    basename: 'image',
    url: 'https://www.datocms-assets.com/45/1496845848-different-image-name.png',
    format: 'jpg',
    author: 'New author!',
    copyright: 'New copyright',
    notes: null,
    default_field_metadata: {
    en: {
    alt: 'new default alt',
    title: 'new default title',
    focal_point: {
    x: 0.3,
    y: 0.6,
    },
    custom_data: {
    watermark: true,
    },
    },
    },
    is_image: true,
    tags: [],
    };
    Create an upload (in the browser)

    This example shows how to add assets to the Media Area from the browser, starting from a File or Blob object.

    Important! Make sure to use the @datocms/cma-client-browser package, or the client.uploads.createFromFileOrBlob() method won't be available!

    Example code:
    import { buildClient } from '@datocms/cma-client-browser';
    const client = buildClient({ apiToken: '<YOUR_API_TOKEN>' });
    function createUpload(file) {
    return client.uploads.createFromFileOrBlob({
    // File object to upload
    fileOrBlob: file,
    // if you want, you can specify a different base name for the uploaded file
    filename: 'different-image-name.png',
    // skip the upload and return an existing resource if it's already present in the Media Area:
    skipCreationIfAlreadyExists: true,
    // be notified about the progress of the operation.
    onProgress: (info) => {
    // info.type can be one of the following:
    //
    // * DOWNLOADING_FILE: client is downloading the asset from the specified URL
    // * REQUESTING_UPLOAD_URL: client is requesting permission to upload the asset to the DatoCMS CDN
    // * UPLOADING_FILE: client is uploading the asset
    // * CREATING_UPLOAD_OBJECT: client is finalizing the creation of the upload resource
    console.log('Phase:', info.type);
    // Payload information depends on the type of notification
    console.log('Details:', info.payload);
    },
    // specify some additional metadata to the upload resource
    author: 'New author!',
    copyright: 'New copyright',
    default_field_metadata: {
    en: {
    alt: 'New default alt',
    title: 'New default title',
    focal_point: {
    x: 0.3,
    y: 0.6,
    },
    custom_data: {
    watermark: true,
    },
    },
    },
    });
    }
    const fileInput = document.querySelector('input[type="file"]');
    fileInput.addEventListener('change', async (event) => {
    const files = event.target.files;
    for (let file of files) {
    createUpload(file).then((upload) => console.log(upload));
    }
    });
    Returned output:
    const response = {
    id: '4124',
    size: 444,
    width: 30,
    height: 30,
    path: '/45/1496845848-different-image-name.png',
    basename: 'image',
    url: 'https://www.datocms-assets.com/45/1496845848-different-image-name.png',
    format: 'jpg',
    author: 'New author!',
    copyright: 'New copyright',
    notes: null,
    default_field_metadata: {
    en: {
    alt: 'new default alt',
    title: 'new default title',
    focal_point: {
    x: 0.3,
    y: 0.6,
    },
    custom_data: {
    watermark: true,
    },
    },
    },
    is_image: true,
    tags: [],
    };
    Cancelling an upload

    It is possible to cancel an upload operation by calling the .cancel() method on the promise returned by one of the upload creation methods (createFromUrl(), createFromLocalFile() in NodeJS, createFromFileOrBlob() in browser):

    Example code:
    import { buildClient, CanceledPromiseError } from '@datocms/cma-client-browser';
    const client = buildClient({ apiToken: '<YOUR_API_TOKEN>' });
    let cancelablePromise = null;
    document.querySelector('button').addEventListener('click', () => {
    if (cancelablePromise) {
    cancelablePromise.cancel();
    }
    });
    document
    .querySelector('input[type="file"]')
    .addEventListener('change', async (event) => {
    cancelablePromise = client.uploads.createFromFileOrBlob({
    fileOrBlob: event.target.files[0],
    });
    cancelablePromise
    .then((upload) => {
    cancelablePromise = null;
    console.log(upload);
    })
    .catch((e) => {
    if (e instanceof CanceledPromiseError) {
    console.log('User canceled the upload process!');
    } else {
    throw e;
    }
    });
    });