REST API: publicationFilter

Page summary:

Add the optional publicationFilter query parameter to filter results by the relationship between a document's draft and published versions, for example never-published or modified entries. The status parameter still selects whether each result returns its draft or published row. REST defaults to status=published, so pass status=draft for values that only match drafts.

The REST API accepts an optional publicationFilter query parameter when Draft & Publish is enabled. publicationFilter filters results by the relationship between a document's draft and published versions, for example entries never published, or entries modified since they were last published.

Key terms

Strapi Draft & Publish stores each entry as up to 2 database rows for the same document and locale:

• a draft row (publishedAt is empty)
• a published row (publishedAt is set)

The status parameter picks which of the 2 rows to read.

publicationFilter instead selects a group of documents based on how their draft and published rows relate (for example, never published, or draft newer than published). Some of these questions compare the 2 rows, so they cannot be expressed by filtering on publishedAt alone.

publicationFilter selects the group of documents first; status then decides which row (draft or published) is returned for each result. One rule explains most surprises on this page: when status is omitted, REST defaults to status=published before applying publicationFilter, so values that only match drafts, such as never-published, return empty results unless you pass status=draft. Understand the default status details each combination.

This page shows how to use the most common publicationFilter values over REST. For the full list of values, their exact definitions, and every status combination, see Document Service API: publicationFilter, which is the reference for the underlying model.

Prerequisites

The Draft & Publish feature must be enabled on the content-type.

Get never-published draft documents

never-published matches documents with no published version for that locale, so only draft rows exist. Pass status=draft, because REST defaults to status=published:

GET/api/restaurants?status=draft&publicationFilter=never-published

RESTJavaScript

GET/api/restaurants?status=draft&publicationFilter=never-published

GET /api/restaurants?status=draft&publicationFilter=never-published

200 OK

{
"data": [
  {
    "documentId": "a1b2c3d4e5f6g7h8i9j0klm",
    "name": "New Restaurant",
    "publishedAt": null,
    "locale": "en"
  }
],
"meta": {
  "pagination": {
    "page": 1,
    "pageSize": 25,
    "pageCount": 1,
    "total": 1
  }
}
}

Get modified documents

modified matches documents whose draft is newer than their published version. With no status parameter, REST returns the published rows of those documents. Pass status=draft to return the newer draft rows instead:

GET/api/restaurants?publicationFilter=modified

RESTJavaScript

GET/api/restaurants?publicationFilter=modified

GET /api/restaurants?publicationFilter=modified

200 OK

{
"data": [
  {
    "documentId": "znrlzntu9ei5onjvwfaalu2v",
    "name": "Biscotte Restaurant",
    "publishedAt": "2024-03-14T15:40:45.330Z",
    "locale": "en"
  }
],
"meta": {
  "pagination": {
    "page": 1,
    "pageSize": 25,
    "pageCount": 1,
    "total": 1
  }
}
}

Get published documents without a draft

published-without-draft matches published rows that have no draft for the same (documentId, locale). REST defaults to status=published, so you can omit status:

GET/api/restaurants?publicationFilter=published-without-draft

RESTJavaScript

GET/api/restaurants?publicationFilter=published-without-draft

GET /api/restaurants?publicationFilter=published-without-draft

200 OK

{
"data": [
  {
    "documentId": "abcdefghijklmno456",
    "name": "Legacy Restaurant",
    "publishedAt": "2024-01-10T09:15:00.000Z",
    "locale": "en"
  }
],
"meta": {
  "pagination": {
    "page": 1,
    "pageSize": 25,
    "pageCount": 1,
    "total": 1
  }
}
}

Understand the default status

When status is omitted, REST defaults to status=published before applying publicationFilter. This is the most common source of unexpected empty results: a value that only matches drafts, such as never-published, returns nothing under the default status. The table below shows the effect for the values used above:

Query	Returns	Why
?publicationFilter=never-published	Empty	never-published matches draft rows only; the default status is published
?status=draft&publicationFilter=never-published	Never-published draft rows	status=draft reads the draft row
?publicationFilter=modified	Published rows of modified documents	The default status=published reads the live row
?status=draft&publicationFilter=modified	Draft rows of modified documents	status=draft reads the newer draft
?publicationFilter=published-without-draft	Published rows with no draft	The default status=published is correct here

The Document Service API defaults to status=draft instead (see Document Service API: publicationFilter).

Reference: accepted values

REST accepts these kebab-case values: never-published, has-published-version, modified, unmodified, never-published-document, has-published-version-document, published-without-draft, published-with-draft. Invalid values return HTTP 400.

Each value, its scope (pair, meaning one documentId and locale at a time, or document, meaning across all locales), and its exact definition are documented on Document Service API: publicationFilter.

Combine with other parameters

publicationFilter can be combined with filters, locale, populate, and other REST parameters. All conditions are applied together.