Skip to main content

Document Service API: Usage with Draft & Publish

By default the Document Service API returns the draft version of a document when the Draft & Publish feature is enabled. This page describes how to use the status and hasPublishedVersion parameters to:

  • return the published version of a document,
  • filter documents by whether they have ever been published,
  • count documents depending on their status,
  • directly publish a document while creating it or updating it.
Note

Passing { status: 'draft' } to a Document Service API query returns the same results as not passing any status parameter.

Get the published version with findOne()​

findOne() queries return the draft version of a document by default.

To return the published version while finding a specific document with the Document Service API, pass status: 'published':

Example request
await strapi.documents('api::restaurant.restaurant').findOne({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
  status: 'published'
});
Example response
{
  documentId: "a1b2c3d4e5f6g7h8i9j0klm",
  name: "Biscotte Restaurant",
  publishedAt: "2024-03-14T15:40:45.330Z",
  locale: "en", // default locale
  // …
}

Get the published version with findFirst()​

findFirst() queries return the draft version of a document by default.

To return the published version while finding the first document with the Document Service API, pass status: 'published':

Example request
const document = await strapi.documents("api::restaurant.restaurant").findFirst({
  status: 'published',
});
Example response
{
  documentId: "a1b2c3d4e5f6g7h8i9j0klm",
  name: "Biscotte Restaurant",
  publishedAt: "2024-03-14T15:40:45.330Z",
  locale: "en", // default locale
  // …
}

Get the published version with findMany()​

findMany() queries return the draft version of documents by default.

To return the published version while finding documents with the Document Service API, pass status: 'published':

Example request
const documents = await strapi.documents("api::restaurant.restaurant").findMany({
  status: 'published'
});
Example response
[
  {
    documentId: "a1b2c3d4e5f6g7h8i9j0klm",
    name: "Biscotte Restaurant",
    publishedAt: "2024-03-14T15:40:45.330Z",
    locale: "en", // default locale
    // …
  }
  // …
]

count() only draft or published versions​

To take into account only draft or published versions of documents while counting documents with the Document Service API, pass the corresponding status parameter:

// Count draft documents (also actually includes published documents)
const draftsCount = await strapi.documents("api::restaurant.restaurant").count({
  status: 'draft'
});
// Count only published documents
const publishedCount = await strapi.documents("api::restaurant.restaurant").count({
  status: 'published'
});
Note

Since published documents necessarily also have a draft counterpart, a published document is still counted as having a draft version.

This means that counting with the status: 'draft' parameter still returns the total number of documents matching other parameters, even if some documents have already been published and are not displayed as "draft" or "modified" in the Content Manager anymore. To count only documents that have never been published, use the hasPublishedVersion parameter.

Create a draft and publish it​

To automatically publish a document while creating it, add status: 'published' to parameters passed to create():

Example request
await strapi.documents('api::restaurant.restaurant').create({
  data: {
    name: "New Restaurant",
  },
  status: 'published',
})
Example response
{
  documentId: "d41r46wac4xix5vpba7561at",
  name: "New Restaurant",
  publishedAt: "2024-03-14T17:29:03.399Z",
  locale: "en" // default locale
  // …
}

Update a draft and publish it​

To automatically publish a document while updating it, add status: 'published' to parameters passed to update():

Example request
await strapi.documents('api::restaurant.restaurant').update({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
  data: {
    name: "Biscotte Restaurant (closed)",
  },
  status: 'published',
})
Example response
{
  documentId: "a1b2c3d4e5f6g7h8i9j0klm",
  name: "Biscotte Restaurant (closed)",
  publishedAt: "2024-03-14T17:29:03.399Z",
  locale: "en" // default locale
  // …
}

Filter by publication history with hasPublishedVersion NewThis content is new.​

The hasPublishedVersion parameter filters documents by whether a published version exists. Use hasPublishedVersion with status: 'draft' to distinguish documents that have never been published from drafts of already-published documents.

The parameter accepts a boolean (true or false) and works with findOne(), findFirst(), findMany(), and count().

Find never-published documents​

Pass hasPublishedVersion: false with status: 'draft' to return only documents that have never been published:

Example request
const documents = await strapi.documents("api::restaurant.restaurant").findMany({
  status: 'draft',
  hasPublishedVersion: false,
});
Example response
[
  {
    documentId: "ln1gkzs6ojl9d707xn6v86mw",
    name: "Restaurant B",
    publishedAt: null, // never published
    locale: "en",
    // …
  },
  // … other never-published documents
]

Find drafts of published documents​

Pass hasPublishedVersion: true with status: 'draft' to return only drafts of documents that have been published at least once:

Example request
const documents = await strapi.documents("api::restaurant.restaurant").findMany({
  status: 'draft',
  hasPublishedVersion: true,
});
Example response
[
  {
    documentId: "a1b2c3d4e5f6g7h8i9j0klm",
    name: "Biscotte Restaurant",
    publishedAt: null, // draft version is returned, but a published version exists
    locale: "en",
    // …
  },
  // …
]
Note

Because the draft version is returned, publishedAt is null even when a published version exists.

Count never-published documents​

Combine hasPublishedVersion: false with count() to count documents that have never been published:

const neverPublishedCount = await strapi.documents("api::restaurant.restaurant").count({
  status: 'draft',
  hasPublishedVersion: false,
});

Combine with other parameters​

hasPublishedVersion can be combined with locale, filters, and populate:

Example request
const documents = await strapi.documents("api::restaurant.restaurant").findMany({
  status: 'draft',
  hasPublishedVersion: false,
  locale: 'en',
  filters: {
    name: { $startsWith: 'Pizzeria' },
  },
});
Example response
[
  {
    documentId: "j9k8l7m6n5o4p3q2r1s0tuv",
    name: "Pizzeria Napoli",
    publishedAt: null,
    locale: "en",
    // …
  },
]
Tip

When hasPublishedVersion is used with populate, the filter also applies to populated relations. Each related document is filtered based on whether a published version exists for it.

Contribute to this page