Document Service API: Populating fields

By default the Document Service API does not populate any relations, media fields, components, or dynamic zones. This page describes how to use the populate parameter to populate specific fields.

Tip

You can also use the select parameter to return only specific fields with the query results (see the select parameter documentation).

Caution

If the Users & Permissions plugin is installed, the find permission must be enabled for the content-types that are being populated. If a role doesn't have access to a content-type it will not be populated.

Relations and media fields

Queries can accept a populate parameter to explicitly define which fields to populate, with the following syntax option examples.

Populate 1 level for all relations

GETstrapi.documents("api::article.article").findMany()

Populate one-level deep for all relations using the wildcard.

GETstrapi.documents("api::article.article").findMany()

const documents = await strapi.documents("api::article.article").findMany({
populate: "*",
});

200 OK

{
[
  {
    "id": "cjld2cjxh0000qzrmn831i7rn",
    "title": "Test Article",
    "slug": "test-article",
    "body": "Test 1",
    // ...
    "headerImage": {
      "data": {
        "id": 1,
        "attributes": {
          "name": "17520.jpg",
          "alternativeText": "17520.jpg",
          "formats": {
            // ...
          }
          // ...
        }
      }
    },
    "author": {
      // ...
    },
    "categories": {
      // ...
    }
  }
  // ...
]
}

Populate 1 level for specific relations

GETstrapi.documents("api::article.article").findMany()

Populate specific relations one-level deep using an array.

GETstrapi.documents("api::article.article").findMany()

const documents = await strapi.documents("api::article.article").findMany({
populate: ["headerImage"],
});

200 OK

[
{
  "id": "cjld2cjxh0000qzrmn831i7rn",
  "title": "Test Article",
  "slug": "test-article",
  "body": "Test 1",
  // ...
  "headerImage": {
    "id": 2,
    "name": "17520.jpg"
    // ...
  }
}
// ...
]

Populate several levels deep for specific relations

GETstrapi.documents("api::article.article").findMany()

Populate specific relations several levels deep using nested populate.

GETstrapi.documents("api::article.article").findMany()

const documents = await strapi.documents("api::article.article").findMany({
populate: {
  categories: {
    populate: ["articles"],
  },
},
});

200 OK

[
{
  "id": "cjld2cjxh0000qzrmn831i7rn",
  "title": "Test Article",
  "slug": "test-article",
  "body": "Test 1",
  // ...
  "categories": {
    "id": 1,
    "name": "Test Category",
    "slug": "test-category",
    "description": "Test 1"
    // ...
    "articles": [
      {
        "id": 1,
        "title": "Test Article",
        "slug": "test-article",
        "body": "Test 1",
        // ...
      }
      // ...
    ]
  }
}
// ...
]

Components & Dynamic Zones

Components are populated the same way as relations:

GETstrapi.documents("api::article.article").findMany()

Populate components using the same syntax as relations.

GETstrapi.documents("api::article.article").findMany()

const documents = await strapi.documents("api::article.article").findMany({
populate: ["testComp"],
});

200 OK

[
{
  "id": "cjld2cjxh0000qzrmn831i7rn",
  "title": "Test Article",
  "slug": "test-article",
  "body": "Test 1",
  // ...
  "testComp": {
    "id": 1,
    "name": "Test Component"
    // ...
  }
}
// ...
]

Dynamic zones are highly dynamic content structures by essence.

GETstrapi.documents("api::article.article").findMany()

Populate dynamic zones using per-component queries with the on property.

GETstrapi.documents("api::article.article").findMany()

const documents = await strapi.documents("api::article.article").findMany({
populate: {
  testDZ: {
    on: {
      "test.test-compo": {
        fields: ["testString"],
        populate: ["testNestedCompo"],
      },
    },
  },
},
});

200 OK

[
{
  "id": "cjld2cjxh0000qzrmn831i7rn",
  "title": "Test Article",
  "slug": "test-article",
  "body": "Test 1",
  // ...
  "testDZ": [
    {
      "id": 3,
      "__component": "test.test-compo",
      "testString": "test1",
      "testNestedCompo": {
        "id": 3,
        "testNestedString": "testNested1"
      }
    }
  ]
}
// ...
]

Populating with create()

POSTstrapi.documents("api::article.article").create()

Populate relations in the response when creating a document.

POSTstrapi.documents("api::article.article").create()

strapi.documents("api::article.article").create({
data: {
  title: "Test Article",
  slug: "test-article",
  body: "Test 1",
  headerImage: 2,
},
populate: ["headerImage"],
});

200 OK

{
"id": "cjld2cjxh0000qzrmn831i7rn",
"title": "Test Article",
"slug": "test-article",
"body": "Test 1",
"headerImage": {
  "id": 2,
  "name": "17520.jpg"
  // ...
}
}

Populating with update()

PUTstrapi.documents("api::article.article").update()

Populate relations in the response when updating a document.

PUTstrapi.documents("api::article.article").update()

strapi.documents("api::article.article").update({
documentId: "cjld2cjxh0000qzrmn831i7rn",
data: {
  title: "Test Article Update",
},
populate: ["headerImage"],
});

200 OK

{
"id": "cjld2cjxh0000qzrmn831i7rn",
"title": "Test Article Update",
"slug": "test-article",
"body": "Test 1",
"headerImage": {
  "id": 2,
  "name": "17520.jpg"
  // ...
}
}

Populating with publish()

Same behavior applies with unpublish() and discardDraft().

POSTstrapi.documents("api::article.article").publish()

Populate relations in the response when publishing a document.

POSTstrapi.documents("api::article.article").publish()

strapi.documents("api::article.article").publish({
documentId: "cjld2cjxh0000qzrmn831i7rn",
populate: ["headerImage"],
});

200 OK

{
"id": "cjld2cjxh0000qzrmn831i7rn",
"versions": [
  {
    "id": "cjld2cjxh0001qzrm1q1i7rn",
    "locale": "en",
    // ...
    "headerImage": {
      "id": 2,
      "name": "17520.jpg"
      // ...
    }
  }
]
}