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

return the published version of a document,
count documents depending on their status,
and directly publish a document while creating it or updating it.

Get the published version with `findOne()` {#find-one}#

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':

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

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

Get the published version with `findFirst()` {#find-first}#

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':

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

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

Get the published version with `findMany()` {#find-many}#

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':

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

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

`count()` only draft or published versions {#count}#

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'
});

Create a draft and publish it {#create}#

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

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

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

Update a draft and publish it {#update}#

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

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

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

Document Service API: Usage with Draft & Publish#

Get the published version with findOne() {#find-one}#

Get the published version with findFirst() {#find-first}#