REST API: publicationFilter
Page summary:Add the optional
publicationFilterquery parameter to query documents by the relationship between their draft and published versions, for example documents that were never published, or documents modified since they were last published. It combines with other query parameters, andstatusstill decides whether you get the draft or the published version.
The publicationFilter is a query parameter that, combined with the status parameter, can help you cover complex queries to find exactly what you need with the REST API.
While status answers "do I want the draft or the published version?", the publicationFilter parameter answers a different question: "which documents do I want, based on how their draft and published versions relate?". This is useful for example to find documents that were never published, or documents whose draft has unsaved changes compared to what is live.
The Draft & Publish feature must be enabled on the content-type. If Draft & Publish is disabled, publicationFilter has no effect.
Available values
publicationFilter accepts one of the following values:
| Value | Selects |
|---|---|
never-published | Documents never published in a given locale |
never-published-document | Documents never published in any locale |
modified | Documents whose draft was edited since it was last published |
unmodified | Documents whose draft has not changed since it was last published |
published-without-draft | Published documents with no draft counterpart |
published-with-draft | Published documents that also have a draft |
has-published-version | Documents that have both a draft and a published version |
has-published-version-document | Documents published in at least one locale (useful when i18n is enabled) |
For detailed examples of how to use the publicationFilter values, including with the status parameter, see the possible use cases table.
- Unknown values return an HTTP
400error. - Values ending in
-documentconsider all locales of a document, which matters when Internationalization (i18n) is enabled: for example,never-published-documentexcludes a document as soon as one of its locales is published. All other values consider one locale at a time. Without i18n, both variants behave the same.
The REST API returns published versions of documents when status is omitted, so queries for draft-only values such as never-published need an explicit status=draft. The Document Service API returns draft versions instead (see Document Service API: publicationFilter).
Possible use cases
The following table lists many possible use cases, illustrating how the status and publicationFilter parameters can be combined to find exactly what you need with the REST API. Click a use case to jump to a complete example:
| I want to… | Use status as… | Use publicationFilter as… |
|---|---|---|
| Find never published drafts | draft | never-published |
| Find drafts never published in any locale | draft | never-published-document |
| Find modified documents | draft or published | modified |
| Find unmodified documents | draft or published | unmodified |
| Find published documents without a draft | published | published-without-draft |
| Find published documents with a draft | published | published-with-draft |
| Find documents with a published version | draft or published | has-published-version |
| Find documents published in at least one locale | draft or published | has-published-version-document |
Pairing a value with the opposite status from the table above is valid but returns nothing rather than an error: for example, never-published with status=published returns an empty result, because these documents have no published version yet.
Examples
The following section lists the most common use cases summed up in the table above.
Find never published drafts
One of the most common use cases is to find the drafts that have never been published. To do so, pass status=draft and publicationFilter=never-published.
This parameter combination works only on a given locale; to find these documents across all locales, use never-published-document instead.
Return the drafts that have never been published for their locale.
curl 'http://localhost:1337/api/restaurants?status=draft&publicationFilter=never-published' \
-H 'Authorization: Bearer <token>'{
"data": [
{
"documentId": "a1b2c3d4e5f6g7h8i9j0klm",
"name": "New Restaurant",
"publishedAt": null,
"locale": "en"
}
],
"meta": {
"pagination": {
"page": 1,
"pageSize": 25,
"pageCount": 1,
"total": 1
}
}
}Find drafts never published in any locale
publicationFilter=never-published-document returns documents that have never been published in any locale. It looks at the whole document across all its locales, not one locale at a time. To find these documents for a given locale only, use never-published instead.
A document counts as published as soon as one of its locales is published: the document is then left out, even the locales that only exist as a draft. The example below returns the draft versions of documents that were never published anywhere:
Return the drafts of documents never published in any locale.
curl 'http://localhost:1337/api/restaurants?status=draft&publicationFilter=never-published-document' \
-H 'Authorization: Bearer <token>'{
"data": [
{
"documentId": "d41r46wac4xix5vpba7561at",
"name": "New Restaurant",
"publishedAt": null,
"locale": "en"
}
],
"meta": {
"pagination": {
"page": 1,
"pageSize": 25,
"pageCount": 1,
"total": 1
}
}
}Find modified documents
publicationFilter=modified selects documents whose draft has modified but unpublished changes. status then decides which version of those documents you get back.
For instance, with status=draft, the query returns the draft versions:
Return the draft versions of documents with unpublished changes.
curl 'http://localhost:1337/api/restaurants?status=draft&publicationFilter=modified' \
-H 'Authorization: Bearer <token>'{
"data": [
{
"documentId": "a1b2c3d4e5f6g7h8i9j0klm",
"name": "Biscotte Restaurant (updated)",
"publishedAt": null,
"locale": "en"
}
],
"meta": {
"pagination": {
"page": 1,
"pageSize": 25,
"pageCount": 1,
"total": 1
}
}
}With status=published (the REST default), the same query returns the currently live version of those documents instead:
Return the currently live versions of documents with unpublished changes.
curl 'http://localhost:1337/api/restaurants?publicationFilter=modified' \
-H 'Authorization: Bearer <token>'{
"data": [
{
"documentId": "a1b2c3d4e5f6g7h8i9j0klm",
"name": "Biscotte Restaurant",
"publishedAt": "2024-03-14T15:40:45.330Z",
"locale": "en"
}
],
"meta": {
"pagination": {
"page": 1,
"pageSize": 25,
"pageCount": 1,
"total": 1
}
}
}Find unmodified documents
publicationFilter=unmodified selects documents whose draft has not changed since it was last published. status then decides which version of those documents you get back.
For instance, with status=draft, the query returns the draft versions:
Return the draft versions of documents unchanged since their last publication.
curl 'http://localhost:1337/api/restaurants?status=draft&publicationFilter=unmodified' \
-H 'Authorization: Bearer <token>'{
"data": [
{
"documentId": "a1b2c3d4e5f6g7h8i9j0klm",
"name": "Biscotte Restaurant",
"publishedAt": null,
"locale": "en"
}
],
"meta": {
"pagination": {
"page": 1,
"pageSize": 25,
"pageCount": 1,
"total": 1
}
}
}With status=published (the REST default), the same query returns the currently live version of those documents instead:
Return the currently live versions of documents unchanged since their last publication.
curl 'http://localhost:1337/api/restaurants?publicationFilter=unmodified' \
-H 'Authorization: Bearer <token>'{
"data": [
{
"documentId": "a1b2c3d4e5f6g7h8i9j0klm",
"name": "Biscotte Restaurant",
"publishedAt": "2024-03-14T15:40:45.330Z",
"locale": "en"
}
],
"meta": {
"pagination": {
"page": 1,
"pageSize": 25,
"pageCount": 1,
"total": 1
}
}
}Find published documents without a draft
publicationFilter=published-without-draft selects published documents that have no draft counterpart. It describes published rows, so REST returns them with the default status=published:
Return published documents with no matching draft version for the same locale.
curl 'http://localhost:1337/api/restaurants?publicationFilter=published-without-draft' \
-H 'Authorization: Bearer <token>'{
"data": [
{
"documentId": "j0klm1n2o3p4q5r6s7t8u9v",
"name": "Legacy Restaurant",
"publishedAt": "2024-01-10T09:15:00.000Z",
"locale": "en"
}
],
"meta": {
"pagination": {
"page": 1,
"pageSize": 25,
"pageCount": 1,
"total": 1
}
}
}Find published documents with a draft
publicationFilter=published-with-draft selects published documents that also have a draft. It describes published rows, so REST returns them with the default status=published:
Return published documents that also have a matching draft version for the same locale.
curl 'http://localhost:1337/api/restaurants?publicationFilter=published-with-draft' \
-H 'Authorization: Bearer <token>'{
"data": [
{
"documentId": "a1b2c3d4e5f6g7h8i9j0klm",
"name": "Biscotte Restaurant",
"publishedAt": "2024-03-14T15:40:45.330Z",
"locale": "en"
}
],
"meta": {
"pagination": {
"page": 1,
"pageSize": 25,
"pageCount": 1,
"total": 1
}
}
}Find documents with a published version
publicationFilter=has-published-version selects documents that have both a draft and a published version for the same locale. status then decides which version of those documents you get back. Unlike published-without-draft, it excludes published documents that have no draft counterpart.
For instance, with status=draft, the query returns the draft versions:
Return the draft versions of documents that also have a published version for the same locale.
curl 'http://localhost:1337/api/restaurants?status=draft&publicationFilter=has-published-version' \
-H 'Authorization: Bearer <token>'{
"data": [
{
"documentId": "a1b2c3d4e5f6g7h8i9j0klm",
"name": "Biscotte Restaurant",
"publishedAt": null,
"locale": "en"
}
],
"meta": {
"pagination": {
"page": 1,
"pageSize": 25,
"pageCount": 1,
"total": 1
}
}
}With status=published (the REST default), the same query returns the currently live version of those documents instead:
Return the currently live versions of documents that also have a published version for the same locale.
curl 'http://localhost:1337/api/restaurants?publicationFilter=has-published-version' \
-H 'Authorization: Bearer <token>'{
"data": [
{
"documentId": "a1b2c3d4e5f6g7h8i9j0klm",
"name": "Biscotte Restaurant",
"publishedAt": "2024-03-14T15:40:45.330Z",
"locale": "en"
}
],
"meta": {
"pagination": {
"page": 1,
"pageSize": 25,
"pageCount": 1,
"total": 1
}
}
}Find documents published in at least one locale
publicationFilter=has-published-version-document considers all locales, so it matches a document as soon as one of its locales is published. With status=draft, it returns the draft versions of every locale of those documents, including locales that were never published themselves:
Return the draft versions of documents published in at least one locale.
curl 'http://localhost:1337/api/restaurants?status=draft&publicationFilter=has-published-version-document' \
-H 'Authorization: Bearer <token>'{
"data": [
{
"documentId": "a1b2c3d4e5f6g7h8i9j0klm",
"name": "Biscotte Restaurant",
"publishedAt": null,
"locale": "en"
}
],
"meta": {
"pagination": {
"page": 1,
"pageSize": 25,
"pageCount": 1,
"total": 1
}
}
}Combine with other parameters
publicationFilter can be combined with filters, locale, populate, and other REST parameters. All conditions are applied together.
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.