Document Service API
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.
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.
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 | If Draft & Publish is enabled for the content-type: Publication status, can be:
| '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:
await strapi.documents('api:restaurant.restaurant').findOne({
documentId: 'a1b2c3d4e5f6g7h8i9j0klm'
})
{
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 | If Draft & Publish is enabled for the content-type: Publication status, can be:
| '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):
await strapi.documents('api::restaurant.restaurant').findFirst()
{
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:
await strapi.documents('api::restaurant.restaurant').findFirst(
{
filters: {
name: {
$startsWith: "Pizzeria"
}
}
}
)
{
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 | If Draft & Publish is enabled for the content-type: Publication status, can be:
| '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:
await strapi.documents('api::restaurant.restaurant').findMany()
[
{
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:
await strapi.documents('api::restaurant.restaurant').findMany(
{
filters: {
name: {
$startsWith: 'Pizzeria'
}
}
}
)
[
{
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 |
status | If Draft & Publish is enabled for the content-type: Can be set to 'published' to automatically publish the draft version of a document while creating it | - | 'published' |
populate | Populate results with additional fields. | null | Object |
Example
If no locale
parameter is passed, create()
creates the draft version of the document for the default locale:
await strapi.documents('api::restaurant.restaurant').create({
data: {
name: 'Restaurant B'
}
})
{
documentId: "ln1gkzs6ojl9d707xn6v86mw",
name: "Restaurant B",
publishedAt: null,
locale: "en",
}
If the Draft & Publish feature is enabled on the content-type, you can automatically publish a document while creating it (see status
documentation).
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 |
status | If Draft & Publish is enabled for the content-type: Can be set to 'published' to automatically publish the draft version of a document while updating it | - | 'published' |
populate | Populate results with additional fields. | null | Object |
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 withpublish()
, - or directly add
status: 'published'
along with the other parameters passed toupdate()
(seestatus
documentation).
Example
If no locale
parameter is passed, update()
updates the document for the default locale:
await strapi.documents('api::restaurant.restaurant').update({
documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
data: { name: "New restaurant name" }
})
{
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:
await strapi.documents('api::restaurant.restaurant').delete({
documentId: 'a1b2c3d4e5f6g7h8i9j0klm', // documentId,
})
{
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:
await strapi.documents('api::restaurant.restaurant').publish({
documentId: 'a1b2c3d4e5f6g7h8i9j0klm',
});
{
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:
await strapi.documents('api::restaurant.restaurant').unpublish({
documentId: 'a1b2c3d4e5f6g7h8i9j0klm'
});
{
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 |