Filtering results

Use search for a free-form search term and query for structured conditions. Prezly Query Language is the JSON syntax used by query; it is not SQL, and it is not a general MongoDB query interface.

The available filters and operators depend on the endpoint and field. This guide uses List Stories. A field appearing in a response does not automatically make it filterable, and a filter never expands your credential's access.

Send a JSON filterCopy Anchor Link

To retrieve public, published stories from one newsroom, replace YOUR_NEWSROOM_UUID with the UUID returned by List Newsrooms:

curl --fail-with-body --silent --show-error --get 'https://api.prezly.com/v2/stories' \
  --header "Authorization: Bearer $PREZLY_API_TOKEN" \
  --header 'Accept: application/json' \
  --data-urlencode 'query={"newsroom.uuid":{"$in":["YOUR_NEWSROOM_UUID"]},"status":{"$in":["published"]},"visibility":{"$in":["public"]}}' \
  --data-urlencode 'sort=-published_at' \
  --data-urlencode 'limit=50' \
  --data-urlencode 'offset=0'

Load the token as shown in Your first API request. This request needs stories:read for a personal token.

The query, formatted for readability, is:

{
  "newsroom.uuid": { "$in": ["YOUR_NEWSROOM_UUID"] },
  "status": { "$in": ["published"] },
  "visibility": { "$in": ["public"] }
}

All three conditions must match. status and visibility are separate: published content is not necessarily public. Choose both deliberately when selecting content for a public website.

In a shell, single quotes around the JSON preserve operator names such as $in. cURL's --data-urlencode handles the URL encoding. In JavaScript, construct an object, serialize it with JSON.stringify, and pass it through URLSearchParams, as in the pagination example.

Choose an operator the field supportsCopy Anchor Link

Simple equality can be written as {"uuid":"YOUR_STORY_UUID"} or with $eq where the field supports equality. Other fields expect an operator and array, such as status with $in. Do not replace every $in expression with a scalar value.

For stories, these are useful starting points:

Use current filter names such as status, language, and locale when building new integrations. Older examples may use lifecycle_status, boolean publication filters, or culture. For a complete endpoint-specific filter list, see the Search Stories reference.

Combine conditions with ANDCopy Anchor Link

Different keys in one query are implicitly joined with AND. Use an explicit $and array when you need multiple conditions on the same field. JSON objects cannot safely represent the same key twice.

For example, select published stories with a publication timestamp in January 2026:

{
  "$and": [
    { "status": { "$in": ["published"] } },
    { "published_at": { "$ge": "2026-01-01T00:00:00Z" } },
    { "published_at": { "$lt": "2026-02-01T00:00:00Z" } }
  ]
}

The lower bound is inclusive and the upper bound is exclusive. Use ISO 8601 timestamps with an explicit timezone, such as Z for UTC, to express the intended interval.

Do not put $ge and $lt together inside a single field's operator object. Use separate conditions as above. Logical $or and $not are not implemented. For alternatives on one single-valued field, use $in with several values instead.

Date filters that support $date and $ndate can also accept named ranges such as today, this_month, or last_30_days, or a pair of date bounds. Prefer explicit timestamps when you need a reproducible interval rather than a range that changes as time passes.

Search within the filtered resultsCopy Anchor Link

On List Stories, you can add --data-urlencode 'search=annual report' to the cURL request above. The search term narrows the structured query rather than replacing it. Search is not an exact identifier lookup; use a UUID filter or Get Story for a known story.

Keep the same query, search term, and sort order while paginating. An empty stories array means no accessible records matched that request. An error response means the request failed; check the error details before changing or removing filters.