Create a new upload - Upload - Content Management API

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 JS or Ruby client to upload new assets, as they provide helper methods that take care of all the details for you.

Parameters

path string Optional

Upload path

author string, null Optional

Author

notes string, null Optional

Notes

defaultFieldMetadata object Optional

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

tags Array<string> Optional

Returns

Returns a upload object.

Create an upload in Node.js

This example shows how to upload local and remote files.

Example code:

const { SiteClient } = require("datocms-client");
const client = new SiteClient("YOUR-API-TOKEN");
async function createUpload() {
  // upload file using URL:
  const path = await client.createUploadPath(
    "http://i.giphy.com/NXOF5rlaSXdAc.gif"
  );
  // ...or using local files:
  const path = await client.createUploadPath("./image.png");
  // you can then use the returned path to create a new upload:
  const upload = await client.uploads.create({
    path,
    author: "New author!",
    copyright: "New copyright",
    defaultFieldMetadata: {
      en: {
        alt: "New default alt",
        title: "New default title",
        focalPoint: {
          x: 0.3,
          y: 0.6,
        },
        customData: {
          watermark: true,
        },
      },
    },
  });
  console.log(upload);
}
createUpload();

Returned output:

{
  id: "4124",
  size: 444,
  width: 30,
  height: 30,
  path: "/45/1496845848-image.png",
  basename: "image",
  url: "https://www.datocms-assets.com/45/1496845848-image.png",
  format: "jpg",
  author: "New author!",
  copyright: "New copyright",
  notes: null,
  defaultFieldMetadata: {
    en: {
      alt: "new default alt",
      title: "new default title",
      focalPoint: {
        x: 0.3,
        y: 0.6,
      },
      customData: {
        watermark: true
      }
    }
  },
  isImage: true,
  tags: []
}

Create an upload in the browser

This example shows how to upload a local file.

Example code:

/*
  Include the client as a script tag
  <script src="https://unpkg.com/datocms-client@latest/dist/client.js"></script>
*/
const client = new Dato.SiteClient("YOUR-API-TOKEN");
async function createUpload(file) {
  // upload File object
  const path = await client.createUploadPath(file);
  // you can then use the returned path to create a new upload:
  const upload = await client.uploads.create({
    path,
    author: "New author!",
    copyright: "New copyright",
    defaultFieldMetadata: {
      en: {
        alt: "New default alt",
        title: "New default title",
        focalPoint: {
          x: 0.3,
          y: 0.6,
        },
        customData: {
          watermark: true,
        },
      },
    },
  });
  return upload;
}
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:

{
  id: "4124",
  size: 444,
  width: 30,
  height: 30,
  path: "/45/1496845848-image.png",
  basename: "image",
  url: "https://www.datocms-assets.com/45/1496845848-image.png",
  format: "jpg",
  author: "New author!",
  copyright: "New copyright",
  notes: null,
  defaultFieldMetadata: {
    en: {
      alt: "new default alt",
      title: "new default title",
      focalPoint: {
        x: 0.3,
        y: 0.6,
      },
      customData: {
        watermark: true
      }
    }
  },
  isImage: true,
  tags: []
}

Advanced options

You can track the upload progress with the onProgress callback option and assign a custom name to the upload file with the filename option.

Example code:

const path = await client.createUploadPath(file, {
  filename: "custom-name.jpg",
  onProgress: (event) => {
    const { type, payload } = event;
    switch (type) {
      // fired before starting upload
      case "uploadRequestComplete":
        console.log(payload.id, payload.url);
        break;
      // fired during upload
      case "upload":
        console.log(payload.percent);
        break;
      // (Node.js only) fired during download of a remote file
      case "download":
        console.log(payload.percent);
        break;
      default:
        break;
    }
  },
});

Returned output:

> node example.js
{
  "id": "666",
  "size": 444,
  "width": 30,
  "height": 30,
  "path": "/45/1496845848-digital-cats.jpg",
  "basename": "digital-cats",
  "filename": "digital-cats.jpg",
  "url": "https://www.datocms-assets.com/45/1496845848-digital-cats.jpg",
  "format": "jpg",
  "author": "Mark Smith",
  "copyright": "2020 DatoCMS",
  "notes": "Nyan the cat",
  "md5": "873c296d0f2b7ee569f2d7ddaebc0d33",
  "duration": 62,
  "frameRate": 30,
  "blurhash": "LEHV6nWB2yk8pyo0adR*.7kCMdnj",
  "muxPlaybackId": "a1B2c3D4e5F6g7H8i9",
  "muxMp4HighestRes": "high",
  "defaultFieldMetadata": {
    "en": {
      "title": "this is the default title",
      "alt": "this is the default alternate text",
      "customData": {
        "foo": "bar"
      },
      "focalPoint": {
        "x": 0.5,
        "y": 0.5
      }
    }
  },
  "isImage": true,
  "createdAt": "2020-04-21T07:57:11.124Z",
  "updatedAt": "2020-04-21T07:57:11.124Z",
  "mimeType": "image/jpeg",
  "tags": [
    "cats"
  ],
  "smartTags": [
    "robot-cats"
  ],
  "exifInfo": {
    "iso": 10000,
    "model": "ILCE-7",
    "flashMode": 16,
    "focalLength": 35,
    "exposureTime": 0.0166667
  },
  "colors": [
    {
      "red": 206,
      "green": 203,
      "blue": 167,
      "alpha": 255
    },
    {
      "red": 158,
      "green": 163,
      "blue": 93,
      "alpha": 255
    }
  ],
  "creator": "312"
}

Cancelling an upload

It is possible to cancel an upload by calling the cancel method on the promise returned by createUploadPath and uploadFile.

Example code:

const uploadPromise = client.createUploadPath(file);
uploadPromise.catch((error) => {
  console.log("cancelled");
});
uploadPromise.cancel();

Returned output:

// > cancelled

Questions?

We're always happy to help with code or other questions you might have. Search our documentation, forum, contact support, or connect with our sales team. You can chat live with other developers in our Slack channel.