Assets

Asset methods map to /api/files routes. They require a CMS API key with abilities that allow the operation (for example read for listing, create for uploads).

const noma = createClient({ projectId, apiKey })

Upload helpers use multipart/form-data. In Node, pass a Buffer and a filename is assigned automatically unless you use File from a browser or polyfill.

`assets.list`

List assets in the library.

const page = await noma.assets.list({
  search: "hero",
  type: "image",
  paginate: 24,
})

Param	Type	Description
`search`	`string`	Search by filename or metadata when supported.
`type`	`'image' \| 'video' \| 'audio' \| 'document'`	Filter by asset kind.
`paginate`	`number`	Page size.

`assets.get`

Fetch one asset by UUID or internal id string (whatever the API returns as identifier).

const asset = await noma.assets.get(assetId)

`assets.getByFilename`

Resolve an asset by its original filename (URL-encoded on the wire).

const asset = await noma.assets.getByFilename("hero-banner.jpg")

`assets.upload`

Upload a single file. The client may send optional metadata as a JSON string in the metadata form field; the Content API upload route currently validates only the file part. Set alt text and related fields with assets.bulkUpdateMetadata after upload (see Bulk Asset Operations).

// Browser
const input = document.querySelector("input[type=file]") as HTMLInputElement
const file = input.files![0]
await noma.assets.upload(file)
 
// Node (Buffer)
await noma.assets.upload(bufferFromDisk)

Argument	Description
`file`	`File` (browser) or `Buffer` (Node). Other types throw a validation error.
`metadata`	Optional. Sent as JSON in the `metadata` form field if provided; use bulk metadata update to persist editor fields reliably.

`assets.delete`

Delete an asset by id.

await noma.assets.delete(assetId)
await noma.assets.delete(assetId, true) // force when applicable

`assets.bulkUpload`

Upload many files in one request. Each item must be File or Buffer.

await noma.assets.bulkUpload([fileA, fileB, bufferC])

Files are attached as files[] in the multipart body.

`assets.bulkUpdateMetadata`

Patch alt text and related metadata for multiple assets without re-uploading binaries.

await noma.assets.bulkUpdateMetadata({
  items: [
    {
      uuid: assetUuid,
      alt_text: "Revised alt",
      title: "Revised title",
      caption: "Optional caption",
      description: "Optional description",
      author: "Optional author",
      copyright: "Optional copyright",
    },
  ],
})

Content - Reference uploaded assets from media fields on entries.
Error Handling - Upload failures and network errors.

Assets

Assets

Related

Search documentation