Document Service API Beta

The Document Service API is built on top of the Query Engine API and used to perform CRUD (create, retrieve, update, and delete) operations on documents .

With the Document Service API, you can also count documents and, if Draft & Publish is enabled on the content-type, perform Strapi-specific features such as publishing/unpublishing documents and discarding drafts.

🤓 Entity Service API is deprecated in Strapi 5

The Document Service API is meant to replace the Entity Service API used in Strapi v4 (see Strapi v4 documentation). Additional information on how to transition away from the Entity Service API to the Document Service API can be found in the related migration reference.

✏️ Note

Relations can also be connected, disconnected, and set through the Document Service API just like with the REST API (see the REST API relations documentation for examples).

`findOne()`

Find a document matching the passed documentId and parameters.

Syntax: findOne(parameters: Params) => Document

Parameters

Parameter	Description	Default	Type
`documentId`	Document id		`ID`
`locale`	Locale of the documents to create.	Default locale	String or `undefined`
`status`	Publication status, can be: `'published'` to find only published documents `'draft'` to find only draft documents	`'draft'`	`'published'` or `'draft'`
`fields`	Select fields to return	All fields (except those not populated by default)	Object
`populate`	Populate results with additional fields.	`null`	Object

Example

If only a documentId is passed without any other parameters, findOne() returns the draft version of a document in the default locale:

Find a document by passing its documentId

await strapi.documents('api:restaurant.restaurant').findOne({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm'
})

Example response

{
  documentId: "a1b2c3d4e5f6g7h8i9j0klm",
  name: "Biscotte Restaurant",
  publishedAt: null, // draft version (default)
  locale: "en", // default locale
  // …
}

`findFirst()`

Find the first document matching the parameters.

Syntax: findFirst(parameters: Params) => Document

Parameters

Parameter	Description	Default	Type
`locale`	Locale of the documents to find.	Default locale	String or `undefined`
`status`	Publication status, can be: `'published'` to find only published documents `'draft'` to find only draft documents	`'draft'`	`'published'` or `'draft'`
`filters`	Filters to use	`null`	Object
`fields`	Select fields to return	All fields (except those not populate by default)	Object
`populate`	Populate results with additional fields.	`null`	Object

Examples

Generic example

By default, findFirst() returns the draft version, in the default locale, of the first document for the passed unique identifier (collection type id or single type id):

Find the first document

await strapi.documents('api::restaurant.restaurant').findFirst()

Example response

{
  documentId: "a1b2c3d4e5f6g7h8i9j0klm",
  name: "Restaurant Biscotte",
  publishedAt: null,
  locale: "en"
  // …
}

Find the first document matching parameters

Pass some parameters to findFirst() to return the first document matching them.

If no locale or status parameters are passed, results return the draft version for the default locale:

Find the first document that matches the defined filters

await strapi.documents('api::restaurant.restaurant').findFirst(
  {
    filters: {
      name: {
        $startsWith: "Pizzeria"
      }
    }
  }
)

Example response

{
  documentId: "j9k8l7m6n5o4p3q2r1s0tuv",
  name: "Pizzeria Arrivederci",
  publishedAt: null,
  locale: "en"
  // …
}

`findMany()`

Find documents matching the parameters.

Syntax: findMany(parameters: Params) => Document[]

Parameters

Parameter	Description	Default	Type
`locale`	Locale of the documents to find.	Default locale	String or `undefined`
`status`	Publication status, can be: `'published'` to find only published documents `'draft'` to find only draft documents	`'draft'`	`'published'` or `'draft'`
`filters`	Filters to use	`null`	Object
`fields`	Select fields to return	All fields (except those not populate by default)	Object
`populate`	Populate results with additional fields.	`null`	Object
`pagination`	Paginate results
`sort`	Sort results

Examples

Generic example

When no parameter is passed, findMany() returns the draft version in the default locale for each document:

Find documents that match a specific filter

await strapi.documents('api::restaurant.restaurant').findMany()

Example response

[
  {
    documentId: "a1b2c3d4e5f6g7h8i9j0klm",
    name: "Biscotte Restaurant",
    publishedAt: null, // draft version (default)
    locale: "en" // default locale
    // …
  },
  {
    documentId: "j9k8l7m6n5o4p3q2r1s0tuv",
    name: "Pizzeria Arrivederci",
    publishedAt: null,
    locale: "en"
    // …
  },
]

Find documents matching parameters

Available filters are detailed in the filters page of the Document Service API reference.

If no locale or status parameters are passed, results return the draft version for the default locale:

Find documents that match a specific filter

await strapi.documents('api::restaurant.restaurant').findMany(
  {
    filters: {  
      name: {
        $startsWith: 'Pizzeria'
      }
    }
  }
)

Example response

[
  {
    documentId: "j9k8l7m6n5o4p3q2r1s0tuv",
    name: "Pizzeria Arrivederci",
    locale: "en", // default locale
    publishedAt: null, // draft version (default)
    // …
  }, 
  // …
]

`create()`

Creates a drafted document and returns it.

Pass fields for the content to create in a data object.

Syntax: create(parameters: Params) => Document

Parameters

Parameter	Description	Default	Type
`locale`	Locale of the documents to create.	Default locale	String or `undefined`
`fields`	Select fields to return	All fields (except those not populated by default)	Object
`populate`	Populate results with additional fields.	`null`	Object

Examples

Generic example

If no locale parameter is passed, create() creates the draft version of the document for the default locale:

Create a new 'Restaurant B' document

await strapi.documents('api::restaurant.restaurant').create({
  data: {
    name: 'Restaurant B'
  }
})

Example response

{
  documentId: "ln1gkzs6ojl9d707xn6v86mw",
  name: "Restaurant B",
  publishedAt: null,
  locale: "en",
}

Auto-publish a document

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()`

Updates document versions and returns them.

Syntax: update(parameters: Params) => Promise<Document>

Parameters

Parameter	Description	Default	Type
`documentId`	Document id		`ID`
`locale`	Locale of the document to update.	Default locale	String or `null`
`filters`	Filters to use	`null`	Object
`fields`	Select fields to return	All fields (except those not populate by default)	Object
`populate`	Populate results with additional fields.	`null`	Object

💡 Tip

Published versions are read-only, so you can not technically update the published version of a document. To update a document and publish the new version right away, you can:

update its draft version with update(), then publish it with publish(),
or directly add status: 'published' along with the other parameters passed to update().

Example

If no locale parameter is passed, update() updates the document for the default locale:

Example request

await strapi.documents('api::restaurant.restaurant').update({ 
    documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
    data: { name: "New restaurant name" }
})

Example response

{
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
  name: "New restaurant name",
  locale: "en",
  publishedAt: null, // draft
  // …
}

`delete()`

Deletes one document, or a specific locale of it.

Syntax: delete(parameters: Params): Promise<{ documentId: ID, entries: Number }>

Parameters

Parameter	Description	Default	Type
`documentId`	Document id		`ID`
`locale`	Locale version of the document to delete.	`null` (deletes only the default locale)	String, `'*'`, or `null`
`filters`	Filters to use	`null`	Object
`fields`	Select fields to return	All fields (except those not populate by default)	Object
`populate`	Populate results with additional fields.	`null`	Object

Example

If no locale parameter is passed, delete() only deletes the default locale version of a document. This deletes both the draft and published versions:

Example request

await strapi.documents('api::restaurant.restaurant').delete({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm', // documentId,
})

Example response

{
  documentId: "a1b2c3d4e5f6g7h8i9j0klm",
  entries: [
    {
      "documentId": "a1b2c3d4e5f6g7h8i9j0klm",
      "name": "Biscotte Restaurant",
      "publishedAt": "2024-03-14T18:30:48.870Z",
      "locale": "en"
      // …
    }
  ]
}

`publish()`

Publishes one or multiple locales of a document.

This method is only available if Draft & Publish is enabled on the content-type.

Syntax: publish(parameters: Params): Promise<{ documentId: ID, entries: Number }>

Parameters

Parameter	Description	Default	Type
`documentId`	Document id		`ID`
`locale`	Locale of the documents to publish.	Only the default locale	String, `'*'`, or `null`
`filters`	Filters to use	`null`	Object
`fields`	Select fields to return	All fields (except those not populate by default)	Object
`populate`	Populate results with additional fields.	`null`	Object

Example

If no locale parameter is passed, publish() only publishes the default locale version of the document:

Example request

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

Example response

{
  documentId: "a1b2c3d4e5f6g7h8i9j0klm",
  entries: [
    {
      "documentId": "a1b2c3d4e5f6g7h8i9j0klm",
      "name": "Biscotte Restaurant",
      "publishedAt": "2024-03-14T18:30:48.870Z",
      "locale": "en"
      // …
    }
  ]
}

`unpublish()`

Unpublishes one or all locale versions of a document, and returns how many locale versions were unpublished.

This method is only available if Draft & Publish is enabled on the content-type.

Syntax: unpublish(parameters: Params): Promise<{ documentId: ID, entries: Number }>

Parameters

Parameter	Description	Default	Type
`documentId`	Document id		`ID`
`locale`	Locale of the documents to unpublish.	Only the default locale	String, `'*'`, or `null`
`filters`	Filters to use	`null`	Object
`fields`	Select fields to return	All fields (except those not populate by default)	Object
`populate`	Populate results with additional fields.	`null`	Object

Example

If no locale parameter is passed, unpublish() only unpublishes the default locale version of the document:

Example request

await strapi.documents('api::restaurant.restaurant').unpublish({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm' 
});

Example response

{
  documentId: "lviw819d5htwvga8s3kovdij",
  entries: [
    {
      documentId: "lviw819d5htwvga8s3kovdij",
      name: "Biscotte Restaurant",
      publishedAt: null,
      locale: "en"
      // …
    }
  ]
}

`discardDraft()`

Discards draft data and overrides it with the published version.

This method is only available if Draft & Publish is enabled on the content-type.

Syntax: discardDraft(parameters: Params): Promise<{ documentId: ID, entries: Number }>

Parameters

Parameter	Description	Default	Type
`documentId`	Document id		`ID`
`locale`	Locale of the documents to discard.	Only the default locale.	String, `'*'`, or `null`
`filters`	Filters to use	`null`	Object
`fields`	Select fields to return	All fields (except those not populate by default)	Object
`populate`	Populate results with additional fields.	`null`	Object

Example

If no locale parameter is passed, discardDraft() discards draft data and overrides it with the published version only for the default locale:

Discard draft for the default locale of a document

strapi.documents.discard({
  documentId: 'a1b2c3d4e5f6g7h8i9j0klm', 
});

Example response

{
  documentId: "lviw819d5htwvga8s3kovdij",
  entries: [
    {
      documentId: "lviw819d5htwvga8s3kovdij",
      name: "Biscotte Restaurant",
      publishedAt: null,
      locale: "en"
      // …
    }
  ]
}

`count()`

Count the number of documents that match the provided parameters.

Syntax: count(parameters: Params) => number

Parameters

Parameter	Description	Default	Type
`locale`	Locale of the documents to count	Default locale	String or `null`
`status`	Publication status, can be: `'published'` to find only published documents `'draft'` to find draft documents (will return all documents)	`'draft'`	`'published'` or `'draft'`
`filters`	Filters to use	`null`	Object

✏️ 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. There currently is no way to prevent already published documents from being counted.

Examples

Generic example

If no parameter is passed, the count() method the total number of documents for the default locale:

Example request

await strapi.documents('api::restaurant.restaurant').count()

Count published documents

To count only published documents, pass status: 'published' along with other parameters to the count() method.

If no locale parameter is passed, documents are counted for the default locale.

Example request

strapi.documents('api::restaurant.restaurant').count({ status: 'published' })

Count documents with filters

Any filters can be passed to the count() method.

If no locale and no status parameter is passed, draft documents (which is the total of available documents for the locale since even published documents are counted as having a draft version) are counted only for the default locale:

/**
 * Count number of draft documents (default if status is omitted) 
 * in English (default locale) 
 * whose name starts with 'Pizzeria'
 */
strapi.documents('api::restaurant.restaurant').count({ filters: { name: { $startsWith: "Pizzeria" }}})`

Document Service API Beta

findOne()​

Parameters​

Example​

findFirst()​

Parameters​

Examples​

Generic example​

Find the first document matching parameters​

findMany()​

Parameters​

Examples​

Generic example​

Find documents matching parameters​

create()​

Parameters​

Examples​

Generic example​

Auto-publish a document​

update()​

Parameters​

Example​

delete()​

Parameters​

Example​

publish()​

Parameters​

Example​

unpublish()​

Parameters​

Example​

discardDraft()​

Parameters​

Example​

count()​

Parameters​

Examples​

Generic example​

Count published documents​

Count documents with filters​

`findOne()`

Parameters

Example

`findFirst()`

Parameters

Examples

Generic example

Find the first document matching parameters

`findMany()`

Parameters

Examples

Generic example

Find documents matching parameters

`create()`

Parameters

Examples

Generic example

Auto-publish a document

`update()`

Parameters

Example

`delete()`

Parameters

Example

`publish()`

Parameters

Example

`unpublish()`

Parameters

Example

`discardDraft()`

Parameters

Example

`count()`

Parameters

Examples

Generic example

Count published documents

Count documents with filters