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
| Field | Required | Description |
|---|---|---|
files | Yes | Array of files. Use repeated files[] parts in multipart clients. |
Limits
| Rule | Value |
|---|---|
| Max files per request | 20 |
| Per-file MIME rules | Same 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:
| Field | Type | Description |
|---|---|---|
message | string | Success message |
data | array | New asset objects (same shape as Get an Asset) |
Errors
| Status | When |
|---|---|
| 400 | Missing project-id or project cannot be resolved |
| 401 | Missing or invalid bearer token |
| 403 | Token does not have create (or *) |
| 422 | Validation failed (too many files, empty array, invalid MIME or size) |
| 429 | Rate 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/jsonRequires the update ability on the token.
JSON body
| Field | Type | Description |
|---|---|---|
items | array | Non-empty list, maximum 50 entries |
Each items[] object must include uuid (asset UUID in this project). Optional string fields (all nullable except uuid):
| Field | Max length (when set) |
|---|---|
alt_text | 255 |
title | 255 |
caption | — |
description | — |
author | 255 |
copyright | 255 |
Only keys you send are merged into metadata; omitted keys are left unchanged for that asset.
Response (200)
JSON object:
| Field | Type | Description |
|---|---|---|
message | string | Success message |
data | array | Updated asset objects (with metadata loaded) |
Errors
| Status | When |
|---|---|
| 400 | Missing project-id or project cannot be resolved |
| 401 | Missing or invalid bearer token |
| 403 | Token does not have update (or *) |
| 422 | Validation failed, or one or more UUIDs are not in this project |
| 429 | Rate 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);Related
- Upload an Asset - Single-file upload and validation rules
- List Assets - Browse the library
- Authentication - Abilities (
createvsupdate) - JavaScript SDK -
assets.bulkUpload,assets.bulkUpdateMetadata