Pagination

Folder browse and search return one page of assets at a time. Two values control paging: more in the response, and size in the request.

The more cursor

When a result has more assets beyond the current page, the response carries a more value. To fetch the next page, send it back as the more query parameter on the same call. When the response omits more, you have reached the last page.

GET /assets/search?query=logo            → { assets: [...], more: "p2" }
GET /assets/search?query=logo&more=p2    → { assets: [...], more: "p3" }
GET /assets/search?query=logo&more=p3    → { assets: [...] }            (no more, last page)

Treat more as opaque. Its form (a string token or a number) and meaning differ between providers, so pass it back unchanged rather than computing your own offsets.

The size parameter

size sets how many assets a page contains. It is optional and defaults per provider. Each provider also caps it, so a large size is clamped to the provider's maximum rather than rejected. Keep size stable across the pages of one traversal.

GET /assets/folder/root?size=25

more paginates assets, not folders

more pages through the assets array only. The folders array is not paged by it: depending on the provider you receive the subfolders on the first page alone, or repeated on every page. Read subfolders from the first page and use more to keep pulling assets in the current folder. If you accumulate pages, collect only assets across them (as the example below does), or dedupe folders by id.

Detecting the end

The presence of more is the signal, not the page size. A short page can still be followed by another, and a full page can be the last. Loop until the response has no more.

async function listAllAssets(folderId: string) {
  const assets = []
  let more: string | number | undefined

  do {
    const url = new URL(`${BASE_URL}/assets/folder/${encodeURIComponent(folderId)}`)
    if (more !== undefined) url.searchParams.set('more', String(more))

    const response = await fetch(url, {
      headers: {
        Authorization: `Bearer ${ciHubAccessToken}`,
        'provider-authorization': `Bearer ${damProviderToken}`,
      },
    })

    if (!response.ok) {
      const { error } = await response.json()
      throw new Error(`${error.code}: ${error.message}`)
    }

    const page = await response.json()
    assets.push(...page.assets)
    more = page.more
  } while (more !== undefined)

  return assets
}

Next