Newsrooms, languages, and categories

A story belongs to one newsroom and one locale. Before creating or publishing it, check the destination's identity, public availability, languages, and categories. Reading a newsroom through the API does not mean its website is online.

This guide inspects existing configuration before authoring a story. For administration, follow Create and configure a newsroom, Manage newsroom categories, or Manage newsroom languages.

Choose the newsroom explicitlyCopy Anchor Link

Start with List Newsrooms, copy the intended newsroom's uuid, then use Get Newsroom to inspect it. Use the UUID throughout your integration instead of assuming the account's default newsroom is the right destination.

Personal tokens need sites:read for the reads in this guide, alongside the owner's newsroom access. Load PREZLY_API_TOKEN as shown in Your first API request.

The newsroom response includes status, is_online, timezone, and its public url. An inactive, offline, or archived newsroom can still be relevant to an authorized API integration; check its intended use before publishing. Story publication and newsroom availability are separate decisions. For a custom website, its own deployment, filters, and cache determine what readers see.

Inspect languages and categories togetherCopy Anchor Link

Replace YOUR_NEWSROOM_UUID and choose a locale you expect to use. Save this Node.js 22+ script as inspect-newsroom.mjs and run node inspect-newsroom.mjs:

const token = process.env.PREZLY_API_TOKEN;
if (!token) throw new Error('Set PREZLY_API_TOKEN before running this script.');
const newsroomId = 'YOUR_NEWSROOM_UUID';
const locale = 'en';
const base = `https://api.prezly.com/v2/newsrooms/${encodeURIComponent(newsroomId)}`;
async function read(url) {
  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
    signal: AbortSignal.timeout(15_000),
  });
  if (!response.ok) throw new Error(`Prezly returned HTTP ${response.status}.`);
  return response.json();
}
const [{ newsroom }, { languages }, { categories }] = await Promise.all([
  read(base), read(`${base}/languages`), read(`${base}/categories`),
]);
if (newsroom.uuid !== newsroomId) throw new Error('Unexpected newsroom.');
const language = languages.find((item) => item.code === locale);
if (!language) throw new Error(`Locale ${locale} is not configured in this newsroom.`);
console.log(JSON.stringify({
  newsroom: newsroom.uuid,
  status: newsroom.status,
  is_online: newsroom.is_online,
  timezone: newsroom.timezone,
  locale: language.code,
  is_default: language.is_default,
  categories: categories.map(({ id, display_name }) => ({ id, display_name })),
}, null, 2));

The three responses use different envelopes: newsroom, languages, and categories. The language/category lists are configuration collections, not story pages: their responses do not use the story list's pagination object. An empty category list is valid.

Get Newsroom → · List Languages → · List Categories →

Use a configured localeCopy Anchor Link

Match the chosen locale against languages[].code. A locale may include a region, such as nl_NL; do not substitute an English display name or an uppercase language abbreviation. is_default identifies the default, but an integration can deliberately select another configured locale.

When authoring a story, this code goes in the request's culture field. The story response contains a culture reference; search filters use locale for an exact locale or language for the language filter described in Filtering results. These names are not interchangeable in every request.

To inspect company information for a known configured locale, replace the UUID and YOUR_LOCALE:

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

The response uses language and includes company_information. A settings response alone is not proof that a locale is enabled: use the language list for that check. The optional fallback parameter controls fallback company information; it does not enable a locale. The server checks whether that parameter is present, so omit it when you do not want fallback rather than sending fallback=false.

Get Language Settings →

Keep category IDs within their newsroomCopy Anchor Link

Categories use numeric id values. Reuse IDs from the selected newsroom's category list; a category with the same display name in another newsroom is a different record. The i18n map contains locale-specific category information. Avoid treating the general display label as a stable identifier or as a translation for every locale.

To inspect one returned category, replace the UUID and YOUR_CATEGORY_ID:

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

The response uses category. When assigning categories through Create/Update Story, send the intended complete category list. Do not assume supplying a new ID appends it to the stored list.

Get Category →

Prepare the story before changing its lifecycleCopy Anchor Link

Confirm the newsroom, configured locale, content, and categories while the story is a draft. Changes to published content affect the existing story rather than creating a separate review draft. Enabling/removing languages or changing newsroom availability is account configuration work; use the administration guides to plan it separately from an import.

Continue with Publishing stories, Creating and updating stories or Story translations.