Manage newsroom categories

Categories organize stories within a newsroom. Their numeric IDs identify the records; translated names are presentation. A category with the same name in two newsrooms is still two different records.

Read the destination and its configured locales using Newsrooms, languages, and categories. Personal tokens need sites:read for inspection and sites:write for category changes, alongside the owner's newsroom permissions. Load PREZLY_API_TOKEN as shown in Your first API request.

Find existing categories firstCopy Anchor Link

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

The response contains categories and sort; it is a configuration collection rather than a paginated story list. Reuse the returned id when updating an existing category. Compare its locale-specific i18n values before creating another record. A repeated POST creates another category rather than updating the one with a matching name.

Read categories →

Create the translations readers needCopy Anchor Link

Save this as category-create.json. Use locales deliberately selected for your newsroom:

{
  "i18n": {
    "en": { "name": "Company news", "description": "Announcements from Acme" },
    "nl": { "name": "Bedrijfsnieuws", "description": "Nieuws van Acme" }
  },
  "is_featured": false
}

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

Current creation returns 201 Created with category. Store category.id. Each supplied translation needs a non-empty name, up to 100 characters; descriptions allow up to 1,500 characters. A category without a translation for the reader's locale may not appear in that newsroom view. Creating translations does not enable those newsroom languages or translate any stories.

You can also send an uploaded image and set is_featured. Featured presentation does not make a category private or restrict access to the stories assigned to it. Image input follows Images and files.

Create category →

Patch translations without replacing the categoryCopy Anchor Link

Replace YOUR_CATEGORY_ID with the numeric ID from this newsroom:

curl --fail-with-body --silent --show-error --request PATCH 'https://api.prezly.com/v2/newsrooms/YOUR_NEWSROOM_UUID/categories/YOUR_CATEGORY_ID' \
  --header "Authorization: Bearer $PREZLY_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{"i18n":{"en":{"name":"Product and company news"}}}'

The response contains category. Omitted translations remain, and omitted fields in an existing translation remain. The example changes the English name while preserving its description and Dutch translation. Include a name when introducing a new translation so that readers have a usable label.

To remove only the Dutch translation, send {"i18n":{"nl":null}} to the same PATCH endpoint. The locale must be nested under i18n; a top-level {"nl":null} is not the category update contract. Removing one translation preserves the category ID and other translations.

Re-read Get Category and inspect the affected public locale after changing names or visibility-related presentation. A website that caches category navigation must refresh that cache too.

Update category →

Assign stories separately, and delete deliberatelyCopy Anchor Link

Creating or renaming a category does not assign stories to it. When creating/updating a story, send the intended complete category ID list as explained in Creating and updating stories. Category administration uses sites:write; updating a story uses stories:write. Preserve the rest of the story's category selection when adding another ID.

DELETE /newsrooms/{newsroom_id}/categories/{id} removes the whole category and returns 204 No Content. It is different from deleting a locale translation. Review its use in stories, public navigation, and external filters before removal; do not treat the numeric ID as a reusable slot. Category deletion is not a request to delete those stories.

If creation times out, inspect the list before repeating POST. If a patch times out, inspect the category by ID. Recover by observing the requested translations, rather than assuming an empty or lost response means that nothing changed.

Delete category →