List all uploads - Upload - Content Management API

In case of any doubts you can always inspect the network calls that the CMS interface is doing, as it's using the public REST API and you are able to replicate the same calls.

Take a look at the examples below with the most common search scenarios.

Query parameters

filter object Optional

Attributes to filter uploads

locale string Optional

When filter[query] or field[fields] is defined, filter by this locale. Default: environment's main locale

orderBy string Optional

Fields used to order results. Format: <field_name>_<DIRECTION(ASC|DESC)>. You can pass multiple comma separated rules.

page object Optional

Attributes to manage results pagination

Returns

Returns an array of upload objects.

Fetching a filtered list of uploads

You can retrieve a list of uploads filtered by a set of conditions. There are different options and you can combine multiple filters together.

In this example we are filtering by type and size. In particular, we are searching for images bigger than 5MB.

The filtering options are the same as the GraphQL API uploads filters. So please check there all the options.

The only difference is that when using this API you should snake_case the fields instead of camelCasing as in the GraphQL API. For example: in_use instead of inUse.

Example code:

const { SiteClient } = require("datocms-client");
const client = new SiteClient("YOUR-API-TOKEN");
async function getFilteredUploads() {
  const uploads = await client.uploads.all({
    filter: {
      fields: {
        type: {
          eq: "image",
        },
        size: {
          gt: 5000000,
        },
      },
    },
  });
  console.log(uploads);
}
getFilteredUploads();

Returned output:

[
  {
    id: '20042883',
    size: 6000243,
    width: 3510,
    height: 4680,
    path: '/123/1626934514-image.jpg',
    basename: 'image',
    filename: 'image.jpg',
    url: 'https://www.datocms-assets.com/123/1626934514-image.jpg',
    format: 'jpg',
    author: null,
    copyright: null,
    notes: null,
    md5: 'e91cfdc282b249d5f114b163485b1553',
    duration: null,
    frameRate: null,
    blurhash: 'L[Nv}aof_N%M%MWBWBt7x]ofV@az',
    muxPlaybackId: null,
    muxMp4HighestRes: null,
    defaultFieldMetadata: { en: [Object], it: [Object], es: [Object] },
    isImage: true,
    createdAt: '2021-07-22T06:15:29.149Z',
    updatedAt: '2021-08-26T11:11:00.207Z',
    mimeType: 'image/jpeg',
    tags: [],
    smartTags: [
      'clothing',
      'apparel',
      'sleeve',
      'sweater',
      'long sleeve',
      'sweatshirt'
    ],
    exifInfo: {
      iso: 160,
      model: 'Canon EOS 5D Mark IV',
      fNumber: 11,
      flashMode: 16,
      lensModel: 'Canon EF 24-105mm f/4L IS USM',
      focalLength: 50,
      exposureTime: 0.00625
    },
    colors: [ [Object], [Object], [Object], [Object], [Object], [Object] ],
    creator: { id: '111', type: 'account' }
  },
  ...
];

Another example and fetching all pages

Example code:

const SiteClient = require('datocms-client').SiteClient;
const client = new SiteClient('YOUR-API-TOKEN');
client.uploads.all({
  filter: {
    ids: '12,31',
    query: 'foobar',
    fields: {
      type: {
        eq: 'image'
      },
      size: {
        gt: 5000000
      }
    }
  },
  locale: 'it',
  order_by: '_created_at_DESC,size_ASC',
  page: {
    offset: 200,
    limit: 100
  }
})
.then((uploads) => {
    uploads.forEach((upload) => {
      console.log(upload);
    });
  })
.catch((error) => {
  console.error(error);
});
// if you want to fetch all the pages with just one call:
client.uploads.all({
  filter: {
    ids: '12,31',
    query: 'foobar',
    fields: {
      type: {
        eq: 'image'
      },
      size: {
        gt: 5000000
      }
    }
  },
  locale: 'it',
  order_by: '_created_at_DESC,size_ASC'
}, {
  allPages: true
})
.then((uploads) => {
    uploads.forEach((upload) => {
      console.log(upload);
    });
  })

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"
}

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.