Newsroom galleries

A newsroom gallery is a media collection with its own identity, name, visibility, and content document. It is separate from an inline gallery block in a story. A gallery can have a public URL even though your authorized API credential can also read material that should not appear on a public website.

Prepare the newsroom and mediaCopy Anchor Link

Choose the destination newsroom and load your credential. Personal tokens need sites:read for retrieval and sites:write for changes, alongside the owner's newsroom-data permissions. Gallery changes also require the account's media-gallery feature.

Upload images before referencing them, following Images and files. Keep the resulting Prezly image metadata, including UUID, dimensions, and effects. Creating a gallery references those assets; it is not a binary upload request.

List and retrieve galleriesCopy Anchor Link

For a custom public site, explicitly select public galleries. Replace YOUR_NEWSROOM_UUID:

curl --fail-with-body --silent --show-error --get 'https://api.prezly.com/v2/newsrooms/YOUR_NEWSROOM_UUID/galleries' \
  --header "Authorization: Bearer $PREZLY_API_TOKEN" \
  --header 'Accept: application/json' \
  --data-urlencode 'query={"status":{"$eq":"public"}}' \
  --data-urlencode 'limit=5' \
  --data-urlencode 'offset=0' \
  --data-urlencode 'sort=+id'

The response contains galleries, pagination, and sort. Follow Pagination and sorting for the complete selection. Access to a gallery through an administrative credential does not make it public; enforce that selection in your website as well.

Store the returned gallery uuid. To inspect a selected gallery, replace YOUR_GALLERY_UUID:

curl --fail-with-body --silent --show-error 'https://api.prezly.com/v2/newsrooms/YOUR_NEWSROOM_UUID/galleries/YOUR_GALLERY_UUID' \
  --header "Authorization: Bearer $PREZLY_API_TOKEN" \
  --header 'Accept: application/json'

Read gallery.name, status, type, content, images_number/videos_number, and url. The older title and images fields are retained for compatibility; use the current name and content for new integrations. thumbnail_image, when present, is itself a JSON-encoded image string.

List Galleries → · Get Gallery →

Understand the gallery documentCopy Anchor Link

gallery.content is a serialized JSON document string. Parse it once before inspecting nodes. Gallery responses currently serialize that document in format 0.50, independently of the story API's content-format=v6 header. Preserve the returned version and node data when editing an existing gallery; do not relabel its document as a different format.

An image gallery contains one gallery node, or an empty gallery placeholder. The node contains image file objects and captions. A video gallery has a different allowed node set: video/embed nodes and video placeholders. A general story document with paragraphs, titles, and mixed body nodes is not automatically valid gallery content. For a custom image-gallery view, read the gallery node’s images and preserve each file’s effects when building CDN URLs. A renderer that expects a v6 story document cannot consume the 0.50 gallery document unchanged.

Prepare a private image galleryCopy Anchor Link

Save one real, uploaded Prezly image object as gallery-image.json, using the shape described in Images and files. This is not the raw Uploadcare metadata response or an illustrative UUID.

This Node.js 22+ script writes the request file only. Save as prepare-gallery.mjs and run node prepare-gallery.mjs:

import { randomUUID } from 'node:crypto';
import { readFile, writeFile } from 'node:fs/promises';

const file = JSON.parse(await readFile('gallery-image.json', 'utf8'));
if (!file.uuid || !file.mime_type?.startsWith('image/') || !file.original_width || !file.original_height) {
  throw new Error('Use the complete metadata of an uploaded image.');
}
const document = {
  type: 'document',
  version: '2.5',
  children: [{
    type: 'gallery',
    uuid: randomUUID(),
    images: [{ file, caption: 'Acme studio exterior' }],
    layout: 'contained',
    padding: 'S',
    thumbnail_size: 'L',
    children: [{ text: '' }],
  }],
};
const payload = {
  name: 'Acme studio press images',
  status: 'private',
  content: JSON.stringify(document),
};
await writeFile('gallery-draft.json', JSON.stringify(payload, null, 2));
console.log('Wrote a private gallery payload. No gallery was created.');

This uses a supported 2.5 image-gallery input and preserves the uploaded image object. The node UUID is generated separately from the uploaded-file UUID. The outer content value must be a string, rather than a nested document object.

Review the name, caption, image, and status, then create it:

curl --fail-with-body --silent --show-error --request POST 'https://api.prezly.com/v2/newsrooms/YOUR_NEWSROOM_UUID/galleries' \
  --header "Authorization: Bearer $PREZLY_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data-binary @gallery-draft.json

The response is 201 Created with gallery. Store its UUID and inspect the returned content and media. The example uses the default image type. Creating a video gallery uses type: video and valid video content; see the Create Gallery request for its fields.

Create Gallery →

Update content or make the gallery publicCopy Anchor Link

Read the selected gallery before editing. A PATCH preserves omitted fields, but a supplied content replaces the complete gallery document. Preserve images, captions, layout, effects, and node identities you intend to keep. The existing gallery type cannot be changed, including by echoing type back from its response.

Once the media and presentation are ready, deliberately make it public:

curl --fail-with-body --silent --show-error --request PATCH 'https://api.prezly.com/v2/newsrooms/YOUR_NEWSROOM_UUID/galleries/YOUR_GALLERY_UUID' \
  --header "Authorization: Bearer $PREZLY_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{"status":"public"}'

Inspect the returned gallery and its public URL. Newsroom availability, your website's presentation, and your own caches still determine what visitors see. Review image captions and delivery effects in the rendered gallery; gallery creation is not a presentation test.

Update Gallery →

Remove a gallery deliberatelyCopy Anchor Link

curl --fail-with-body --silent --show-error --request DELETE 'https://api.prezly.com/v2/newsrooms/YOUR_NEWSROOM_UUID/galleries/YOUR_GALLERY_UUID' \
  --header "Authorization: Bearer $PREZLY_API_TOKEN" \
  --header 'Accept: application/json'

Successful deletion returns 204 No Content. Remove its listing and cached pages from your own site. Do not treat deleting a gallery as proof that its underlying uploaded files or copies held elsewhere were erased.

A read is not an atomic version check, so coordinate concurrent content editors. If creation times out, reconcile existing galleries before creating another. See Handling errors for validation, access, and feature failures.

Delete Gallery →