Document Service API: Usage with Draft & Publish

Page summary:

Use the status parameter with the Document Service API to retrieve published or draft versions of documents, count documents by status, and directly publish documents during creation or updates.

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 parameter to:

• return the published version of a document,
• return the draft or published version of populated relations,
• count documents depending on their status,
• and 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.

Note

The Document Service API defaults to draft, but the REST API defaults to published. A POST or PUT request sent to the REST API without a status parameter therefore publishes immediately, which is the opposite of the behavior described on this page.

To select documents by how their draft and published versions relate (never-published, modified, and others), see Document Service API: publicationFilter.

Get the published version with findOne()

strapi.documents().findOne()

findOne() with status: 'published'

Return the published version of a specific document.

JavaScript

await strapi.documents('api::restaurant.restaurant').findOne({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
  status: 'published'
});

200 OK

{
  documentId: "a1b2c3d4e5f6g7h8i9j0klm",
  name: "Biscotte Restaurant",
  publishedAt: "2024-03-14T15:40:45.330Z",
  locale: "en", // default locale
  // …
}

Get the published version with findFirst()

strapi.documents().findFirst()

findFirst() with status: 'published'

Return the published version of the first matching document.

JavaScript

const document = await strapi.documents("api::restaurant.restaurant").findFirst({
  status: 'published',
});

200 OK

{
  documentId: "a1b2c3d4e5f6g7h8i9j0klm",
  name: "Biscotte Restaurant",
  publishedAt: "2024-03-14T15:40:45.330Z",
  locale: "en", // default locale
  // …
}

Get the published version with findMany()

strapi.documents().findMany()

findMany() with status: 'published'

Return the published versions of all matching documents.

JavaScript

const documents = await strapi.documents("api::restaurant.restaurant").findMany({
  status: 'published'
});

200 OK

[
  {
    documentId: "a1b2c3d4e5f6g7h8i9j0klm",
    name: "Biscotte Restaurant",
    publishedAt: "2024-03-14T15:40:45.330Z",
    locale: "en", // default locale
    // …
  }
  // …
]

Populate draft or published relations

The status parameter also applies to populated relations. Populated relations return the same version as the queried documents when their content-type has Draft & Publish enabled.

Caution

status is only accepted at the root of the query. Adding it inside a populate object, such as populate: { categories: { status: 'draft' } }, throws a ValidationError with a message such as Invalid key status at categories.

The publicationFilter parameter follows the same rules. It is only accepted at the root of the query, and Strapi filters populated relations with the same value.

The following example returns the published versions of restaurants and of their categories:

strapi.documents().findMany()

findMany() with status: 'published' and populate

Return the published versions of all matching documents and of their populated relations.

JavaScript

const documents = await strapi.documents("api::restaurant.restaurant").findMany({
  status: 'published',
  populate: ['categories'],
});

200 OK

[
  {
    documentId: "a1b2c3d4e5f6g7h8i9j0klm",
    name: "Biscotte Restaurant",
    publishedAt: "2024-03-14T15:40:45.330Z",
    locale: "en", // default locale
    categories: [
      {
        documentId: "z0y2x4w6v8u1t3s5r7q9onm",
        name: "French cuisine",
        publishedAt: "2024-03-14T15:38:12.004Z",
        // …
      }
    ],
    // …
  }
  // …
]

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 never-published drafts, pass a publicationFilter value such as 'never-published' or 'never-published-document'.

Create a draft and publish it

strapi.documents().create()

create() with status: 'published'

Create a new document and immediately publish it.

JavaScript

await strapi.documents('api::restaurant.restaurant').create({
  data: {
    name: "New Restaurant",
  },
  status: 'published',
})

200 OK

{
  documentId: "d41r46wac4xix5vpba7561at",
  name: "New Restaurant",
  publishedAt: "2024-03-14T17:29:03.399Z",
  locale: "en" // default locale
  // …
}

Update a draft and publish it

strapi.documents().update()

update() with status: 'published'

Update an existing document and immediately publish it.

JavaScript

await strapi.documents('api::restaurant.restaurant').update({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
  data: {
    name: "Biscotte Restaurant (closed)",
  },
  status: 'published',
})

200 OK

{
  documentId: "a1b2c3d4e5f6g7h8i9j0klm",
  name: "Biscotte Restaurant (closed)",
  publishedAt: "2024-03-14T17:29:03.399Z",
  locale: "en" // default locale
  // …
}