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 perform Strapi-specific features such as publishing and unpublishing documents and discarding drafts.

`findOne()`

Find a document matching the id and parameters.

Syntax: findOne(id: ID, parameters: Params) => Document

Parameters

Parameter	Description	Default	Type
`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	`'published'`	`'published'` or `'draft'`
`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

Find document by id

await strapi.documents('api::.articles.articles').findOne(
  documentId,
)

Example response

{
  id: documentId,
  locale: 'en', // locale=en (default locale) is the default 
  status: 'draft', 
  // …
}

Find the default locale of a document

If no locale and no published status is specified in the parameters, findOne() returns the published variation of the document for the default locale (i.e., English).

// Returns the published variation of the document for the default locale
await documents(uid).findOne(id);

// Returns the same result as the code above
await documents(uid).findOne(id, { locale: "en", status: "published" })

Find a specific locale of a document

await documents(uid).findOne(id, { locale: 'fr' });

`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	`'published'`	`'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

Find the first document that matches the defined filters

await strapi.documents('api::.articles.articles').findFirst(
  documentId,
  {
    filters: {  
      title: "V5 is coming"
    }
  }
)

Example response

{
  id: documentId,
  locale: 'en', // locale=en (default locale) is the default 
  status: 'draft', 
  title: "V5 is coming"
  // …
}

`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	`'published'`	`'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
`_q`

Examples

Generic example

Find documents that match a specific filter

await strapi.documents('api::.articles.articles').findMany(
  documentId,
  {
    filters: {  
      title: "V5 is coming"
    }
  }
)

Example response

[
  {
    id: documentId,
    locale: 'en', // locale=en (default locale) is the default 
    status: 'draft', 
    title: "V5 is coming"
    // …
  }, 
  // …
]

Find `fr` version of all documents that have a `fr` locale available

await documents(uid).findMany({ locale: 'fr' }); // Defaults to status: published
await documents(uid).findMany(); // Defaults to default locale  and published status

Result:

Given the following 4 documents that have various locales:

Document A:
- en
- fr
- it
Document B:
- en
- it
Document C:
- fr
Document D:
- fr
- it

findMany({ locale: 'fr' }) would only return the documents that have the ‘fr’ version, that is documents A, C, and D.

`create()`

Creates a drafted document and returns it.

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

Update spanish draft locale of a document

strapi.documents.create(
  documentId, 
  { 
    locale: 'es' // defaults to default locale
    data: { title: "Título" }
  } 
)

Example response

{ 
  id: documentId,
  locale: 'es',
  status: 'draft',
  data: { title: "Titulo" }
} 

Create document with specific locale

await documents(uid).create({locale: 'fr', data: {}})

Create document with default locale

await documents(uid).create({data: {}}

Create document draft

await documents(uid).create({data: {}}

Auto publish document

// Creates the document in draft, and publishes it afterwards
await documents(uid).create({autoPublish: true, data: {}}

`update()`

Updates document versions and returns them

Syntax: update(parameters: Params) => Document

Parameters

Parameter	Description	Default	Type
`locale`	Locale of array of locales of the documents to update. Defaults to `null`, which updates all of the document locales at once.	Default locale	String, array of strings, 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

Examples

Generic example

Update spanish draft locale of a document

strapi.documents.update(
  documentId, 
  { 
    locale: 'es'
    data: { title: "Título" }
  } 
)

Example response

{ 
  documents: [
    {
      id: documentId,
      locale: 'es',
      status: 'draft',
      // …
    }
  ] 
} 

Update many document locales

// Updates the default locale by default
await documents(uid).update(docId, {locale: ['es', 'en'], data: {name: "updatedName" }}

Update a given document locale

await documents(uid).update(docId, {locale: 'en', data: {name: "updatedName" }}

// Updates default locale
await documents(uid).update(docId, {data: {name: "updatedName" }}

Auto publish document when updating

// Creates the document in draft, and publishes it afterwards
await documents(uid).update(documentId, {autoPublish: true, data: {}}

`delete()`

Deletes one document, or a specific locale of it.

Syntax:

delete(id: ID, parameters: Params) => { 
  versions: Document[], 
  errors: Errors[]  // Errors occurred when deleting documents
}

Parameters

Parameter	Description	Default	Type
`locale`	Locale of array of locales of the documents to update. Defaults to `null`, which deletes all of the document locales at once.	`null` (all locales)	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

Examples

Generic example

Delete spanish locale of a document

strapi.documents.delete(documentId, { locale: 'es'} )

Example response

{ 
  versions: [
    { id: documentId, locale: 'es', status: 'draft' }
    { id: documentId, locale: 'es', status: 'published' }
  ] 
} 

Delete an entire document

// This would remove the entire document by default
// All its locales and versions
await documents(uid).delete(id, {});

Delete a single locale

// Removes the english locale (both its draft and published versions)
await documents(uid).delete(id, { locale: 'en' });

Delete a document with filters

// Removes the english locale (both its draft and published versions)
await documents(uid).delete(id, { filters: { title: 'V5 is coming' } });

✋ Caution

When deleting, if matched entries delete only the draft version , it will also delete the published version.

`publish()`

Publishes one or multiple locales of a document.

Syntax:

publish(id: ID, parameters: Params) => { 
  id: string, 
  versions: Document[]  // Published versions
}

Parameters

Parameter	Description	Default	Type
`locale`	Locale of the documents to publish. If omitted, publishes all document locales.	All locales	String
`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

Publish english locale of document

strapi.documents.publish(
  documentId, 
  // Publish english locale of document
  { locale: 'en' }
);

Example response

{
  id: documentId,
  documents: [
    {
      id: documentId,
      locale: 'en',
      // …
    }
  ]
}

Publish a document locale

await documents(uid).publish(id, { locale: 'en' });

Publish all document locales

// Publishes all by default
await documents(uid).publish(id);

Publish document locales with filters

// Only publish locales which title is "Ready to publish"
await documents(uid).publish(id, filters: {
  title: 'Ready to publish'
});

`unpublish()`

Unpublishes one or multiple locales of a document.

Syntax:

unpublish(id: ID, parameters: Params) => { 
  id: string, 
  versions: Document[]  // Unpublished versions
}

Parameters

Parameter	Description	Default	Type
`locale`	Locale of the documents to unpublish. If omitted, unpublishes all document locales.	All locales	String
`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

Find document by id

strapi.documents.unpublish(
  documentId, 
  {
    locale: 'en' // Unpublish english locale of document
  }
);

Example response

{
  id: documentId,
  documents: [
    { 
      id: documentId,
      locale: 'en',
      // …
    }
  ]
}

Unpublish a document locale

await documents(uid).publish(id, { locale: 'en' });

Unpublish all document locales

// Unpublishes all by default
await documents(uid).unpublish(id, {});

Unpublish document locales with filters

// Only Unpublish locales which title is "Ready to unpublish"
await documents(uid).unpublish(id, filters: {
  title: 'Ready to unpublish'
});

`discardDraft()`

Discards draft data and overrides it with the published version.

Syntax:

discardDraft(id: ID, parameters: Params) => { 
  id: string, 
  versions: Document[]  // New drafts
}

Parameters

Parameter	Description	Default	Type
`locale`	Locale of the documents to discard. If omitted, discards all draft locales.	All locales	String
`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

Find document by id

strapi.documents.discard(
  documentId, 
  {
    locale: 'en' // Discard english locale draft of document
  }
);

Example response

{
  id: documentId,
  documents: [
    { 
      id: documentId,
      locale: 'en',
      // …
    }
  ]
}

Unpublish a document locale

await documents(uid).publish(id, { locale: 'en' });

Unpublish all document locales

// Unpublishes all by default
await documents(uid).unpublish(id, {});

Unpublish document locales with filters

// Only unpublish locales which title is "Ready to unpublish"
await documents(uid).unpublish(id, filters: {
  title: 'Ready to unpublish'
});

`count()`

Count the number of documents that match the provided filters.

Syntax: count(parameters: Params) => number

Parameters

Parameter	Description	Default	Type
`locale`	Locale of the documents to count, defaults to the default locale of the application.	All locales	String
`status`	Publication status, can be: `'published'` to find only published documents `'draft'` to find only draft documents	`'published'`	`'published'` or `'draft'`
`filters`	Filters to use	`null`	Object

Examples

Generic example

Find document by id

const enArticles = await strapi.documents('api::article.article').count({ locale: 'en' })
// enArticles = 2 

count draft documents in a specific locale

// Count number of draft documents in English
strapi.documents(uid).count({ locale: 'en', status: 'draft' })

Count published documents in a specific locale

// Count number of published documents in French
strapi.documents(uid).count({ locale: 'fr', status: 'published' })

Count documents with filters

/**
 * Count number of published documents (default if status is omitted) 
 * in English (default locale) 
 * that match a title 
 */
strapi.documents(uid).count({ filters: { title: "V5 is coming" } })`

Document Service API

findOne()​

Parameters​

Examples​

Generic example​

Find the default locale of a document​

Find a specific locale of a document​

findFirst()​

Parameters​

Examples​

Generic example​

findMany()​

Parameters​

Examples​

Generic example​

Find fr version of all documents that have a fr locale available​

create()​

Parameters​

Examples​

Generic example​

Create document with specific locale​

Create document with default locale​

Create document draft​

Auto publish document​

update()​

Parameters​

Examples​

Generic example​

Update many document locales​

Update a given document locale​

Auto publish document when updating​

delete()​

Parameters​

Examples​

Generic example​

Delete an entire document​

Delete a single locale​

Delete a document with filters​

publish()​

Parameters​

Examples​

Generic example​

Publish a document locale​

Publish all document locales​

Publish document locales with filters​

unpublish()​

Parameters​

Examples​

Generic example​

Unpublish a document locale​

Unpublish all document locales​

Unpublish document locales with filters​

discardDraft()​

Parameters​

Examples​

Generic example​

Unpublish a document locale​

Unpublish all document locales​

Unpublish document locales with filters​

count()​

Parameters​

Examples​

Generic example​

count draft documents in a specific locale​

Count published documents in a specific locale​

Count documents with filters​

`findOne()`

Parameters

Examples

Generic example

Find the default locale of a document

Find a specific locale of a document

`findFirst()`

Parameters

Examples

Generic example

`findMany()`

Parameters

Examples

Generic example

Find `fr` version of all documents that have a `fr` locale available

`create()`

Parameters

Examples

Generic example

Create document with specific locale

Create document with default locale

Create document draft

Auto publish document

`update()`

Parameters

Examples

Generic example

Update many document locales

Update a given document locale

Auto publish document when updating

`delete()`

Parameters

Examples

Generic example

Delete an entire document

Delete a single locale

Delete a document with filters

`publish()`

Parameters

Examples

Generic example

Publish a document locale

Publish all document locales

Publish document locales with filters

`unpublish()`

Parameters

Examples

Generic example

Unpublish a document locale

Unpublish all document locales

Unpublish document locales with filters

`discardDraft()`

Parameters

Examples

Generic example

Unpublish a document locale

Unpublish all document locales

Unpublish document locales with filters

`count()`

Parameters

Examples

Generic example

count draft documents in a specific locale

Count published documents in a specific locale

Count documents with filters