Noma

Bulk Asset Operations

Bulk Asset Operations

Endpoints for uploading many files in one request and for updating metadata on multiple assets without re-uploading binaries.

Both routes live under /api/files.

Upload many files

Request

POST /api/files/bulk/upload HTTP/1.1
Host: app.nomacms.com
project-id: <project-uuid>
Authorization: Bearer <api-token>
Accept: application/json
Content-Type: multipart/form-data; boundary=...

Requires the create ability on the token.

Form fields

FieldRequiredDescription
filesYesArray of files. Use repeated files[] parts in multipart clients.

Limits

RuleValue
Max files per request20
Per-file MIME rulesSame allowed types as Upload an Asset

If any file fails during processing, already-created assets from the same request are rolled back on the server side when possible.

Response (201)

JSON object:

FieldTypeDescription
messagestringSuccess message
dataarrayNew asset objects (same shape as Get an Asset)

Errors

StatusWhen
400Missing project-id or project cannot be resolved
401Missing or invalid bearer token
403Token does not have create (or *)
422Validation failed (too many files, empty array, invalid MIME or size)
429Rate limited

Update metadata for many assets

Request

PATCH /api/files/bulk/metadata HTTP/1.1
Host: app.nomacms.com
project-id: <project-uuid>
Authorization: Bearer <api-token>
Accept: application/json
Content-Type: application/json

Requires the update ability on the token.

JSON body

FieldTypeDescription
itemsarrayNon-empty list, maximum 50 entries

Each items[] object must include uuid (asset UUID in this project). Optional string fields (all nullable except uuid):

FieldMax length (when set)
alt_text255
title255
caption
description
author255
copyright255

Only keys you send are merged into metadata; omitted keys are left unchanged for that asset.

Response (200)

JSON object:

FieldTypeDescription
messagestringSuccess message
dataarrayUpdated asset objects (with metadata loaded)

Errors

StatusWhen
400Missing project-id or project cannot be resolved
401Missing or invalid bearer token
403Token does not have update (or *)
422Validation failed, or one or more UUIDs are not in this project
429Rate limited

Example

import { createClient } from "@nomacms/js-sdk"
 
const client = createClient({
  projectId: process.env.NOMA_PROJECT_ID!,
  apiKey: process.env.NOMA_API_KEY!,
})
 
await client.assets.bulkUpload([fileA, fileB])
 
await client.assets.bulkUpdateMetadata({
  items: [
    {
      uuid: assetUuid,
      alt_text: "Revised alt",
      title: "Revised title",
    },
  ],
})
import axios from "axios"
import FormData from "form-data"
import fs from "node:fs"
 
async function main() {
  const headersBase = {
    "project-id": process.env.NOMA_PROJECT_ID!,
    Authorization: `Bearer ${process.env.NOMA_API_KEY}`,
    Accept: "application/json",
  }
 
  const form = new FormData()
  form.append("files[]", fs.createReadStream("./a.jpg"))
  form.append("files[]", fs.createReadStream("./b.jpg"))
 
  const upload = await axios.post("https://app.nomacms.com/api/files/bulk/upload", form, {
    headers: { ...form.getHeaders(), ...headersBase },
    maxBodyLength: Infinity,
    maxContentLength: Infinity,
  })
  console.log(upload.data)
 
  const patch = await axios.patch(
    "https://app.nomacms.com/api/files/bulk/metadata",
    {
      items: [{ uuid: process.env.ASSET_UUID!, alt_text: "Revised alt" }],
    },
    { headers: { ...headersBase, "Content-Type": "application/json" } },
  )
  console.log(patch.data)
}
 
void main()
curl -sS -X POST \
  -H "project-id: $NOMA_PROJECT_ID" \
  -H "Authorization: Bearer $NOMA_API_KEY" \
  -H "Accept: application/json" \
  -F "files[]=@./a.jpg" \
  -F "files[]=@./b.jpg" \
  "https://app.nomacms.com/api/files/bulk/upload"
curl -sS -X PATCH \
  -H "project-id: $NOMA_PROJECT_ID" \
  -H "Authorization: Bearer $NOMA_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"uuid":"'"$ASSET_UUID"'","alt_text":"Revised alt"}]}' \
  "https://app.nomacms.com/api/files/bulk/metadata"
<?php
 
$payload = json_encode([
    'items' => [
        ['uuid' => getenv('ASSET_UUID'), 'alt_text' => 'Revised alt'],
    ],
]);
 
$ch = curl_init('https://app.nomacms.com/api/files/bulk/metadata');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'PATCH',
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_HTTPHEADER => [
        'project-id: ' . getenv('NOMA_PROJECT_ID'),
        'Authorization: Bearer ' . getenv('NOMA_API_KEY'),
        'Accept: application/json',
        'Content-Type: application/json',
        'Content-Length: ' . strlen($payload),
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
echo curl_exec($ch);
  • Upload an Asset - Single-file upload and validation rules
  • List Assets - Browse the library
  • Authentication - Abilities (create vs update)
  • JavaScript SDK - assets.bulkUpload, assets.bulkUpdateMetadata

Search documentation

Find guides and reference pages