Show examples in:
    List all uploads

    To retrieve a collection of uploads, send a GET request to the /uploads endpoint. The collection is paginated, so make sure to iterate over all the pages if you need every record in the collection!

    The following table contains the list of all the possible arguments, along with their type, description and examples values.

    Pro tip: in case of any doubts you can always inspect the network calls that the CMS interface is doing, as it's using the Content Management API as well!

    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

    order_by  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 resource objects.

    Examples

    The following examples are available:

    Fetching one page of results vs. the whole collection

    The client.uploads.list() method returns a single page of records, while if you need to iterate over every resource in the collection (and not just the first page of results), you can use the client.uploads.listPagedIterator() method with an async iteration statement, which automatically handles pagination for you:

    Example code:
    import { buildClient } from '@datocms/cma-client-node';
    async function run() {
    const client = buildClient({ apiToken: '<YOUR_API_TOKEN>' });
    // this only returns the first page of results:
    const uploads = await client.uploads.list();
    console.log(uploads);
    // this iterates over every page of results:
    for await (const upload of client.uploads.listPagedIterator()) {
    console.log(upload);
    }
    }
    run();
    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.

    Example code:
    import { buildClient } from '@datocms/cma-client-node';
    async function run() {
    const client = buildClient({ apiToken: '<YOUR_API_TOKEN>' });
    const uploads = await client.uploads.list({
    filter: {
    fields: {
    type: {
    eq: 'image',
    },
    size: {
    gt: 5000000,
    },
    },
    },
    });
    console.log(uploads);
    }
    run();
    Another example
    Example code:
    import { buildClient } from '@datocms/cma-client-node';
    async function run() {
    const client = buildClient({ apiToken: '<YOUR_API_TOKEN>' });
    // this only returns the first page of results:
    const uploads = await client.uploads.list({
    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: 20
    }
    });
    uploads.forEach((upload) => {
    console.log(upload);
    });
    // this iterates over every page of results:
    for await (const upload of client.uploads.listPagedIterator(
    {
    filter: {
    ids: '12,31',
    query: 'foobar',
    fields: {
    type: {
    eq: 'image'
    },
    size: {
    gt: 5000000
    }
    }
    },
    locale: 'it',
    order_by: '_created_at_DESC,size_ASC'
    }
    )) {
    console.log(upload);
    }
    }
    run();
    Returned output:
    {
    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,
    frame_rate: 30,
    blurhash: 'LEHV6nWB2yk8pyo0adR*.7kCMdnj',
    mux_playback_id: 'a1B2c3D4e5F6g7H8i9',
    mux_mp4_highest_res: 'high',
    default_field_metadata: {
    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
    }
    }
    },
    is_image: true,
    created_at: '2020-04-21T07:57:11.124Z',
    updated_at: '2020-04-21T07:57:11.124Z',
    mime_type: 'image/jpeg',
    tags: [
    'cats'
    ],
    smart_tags: [
    'robot-cats'
    ],
    exif_info: {
    iso: 10000,
    model: 'ILCE-7',
    flash_mode: 16,
    focal_length: 35,
    exposure_time: 0.0166667
    },
    colors: [
    {
    red: 206,
    green: 203,
    blue: 167,
    alpha: 255
    },
    {
    red: 158,
    green: 163,
    blue: 93,
    alpha: 255
    }
    ],
    creator: {
    type: 'account',
    id: '312'
    }
    }