> For the complete documentation index, see [llms.txt](https://docs.comfortable.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.comfortable.io/apis/rest-api/filters/includes.md).

# Includes

With the parameter `includes` you can aggregate relations for a document that were defined by `relation fields` for a `content type`.

## Define a general number of included relation levels

<mark style="color:blue;">`GET`</mark> `https://api.cmft.io/v1/<repoName>/<endpoint>?includes=<level>`

#### Path Parameters

| Name     | Type   | Description                          |
| -------- | ------ | ------------------------------------ |
| repoName | string | The API identifier of the repository |
| endpoint | string | The endpoint you'd like to query     |
| include  | number | The levels of includes               |

{% tabs %}
{% tab title="200 " %}

```javascript
// Example for 'includes=1' (aggregate first level)
data: [
{
  "fields": {
    "title": "Roses are red",
    "author": {
      "meta": {
        "id": "323979853562951413",
        "contentType": "author"
      }
    }
  },
  "meta": {
    "id": "314159265358979323",
    "contentType": "poem",
    "repository": "123456789011121415",
    "revision": 1,
    "tags": [],
    "createdAt": "2018-01-01T00:00:00.000Z",
    "updatedAt": "2018-01-01T00:00:00.000Z"
  }
}
],
includes: [
  author: [
    {
      "fields": {
        "name": "Victor Hugo"
      },
      "meta": {
        "id": "323979853562951413",
        "contentType": "author",
        "repository": "123456789011121415",
        "revision": 1,
        "tags": [],
        "createdAt": "2018-01-01T00:00:00.000Z",
        "updatedAt": "2018-01-01T00:00:00.000Z"
      }
    }
  ]
]

```

{% endtab %}
{% endtabs %}

A level of `1` would aggregate all relations, from **all relation fields**, of the first level. \
A level of `2` would also return all of the relations to those documents of the first level. The maximum number of levels is `5`.

## Include relations from specific fields

<mark style="color:blue;">`GET`</mark> `https://api.comft.io/v1/<repoName>/<endpoint>?includes[<field>]=1`

#### Path Parameters

| Name     | Type   | Description                          |
| -------- | ------ | ------------------------------------ |
| repoName | string | The API identifier of the repository |
| endpoint | string | The endpoint you'd like to query     |
| include  | string | The field path you'd like to include |

{% tabs %}
{% tab title="200 " %}

```javascript
/*
 * Example for 'includes[*.fields.author]=1'
 * (aggregate the author field, specifically)
 */
 
data: [
{
  "fields": {
    "title": "Roses are red",
    "author": {
      "meta": {
        "id": "323979853562951413",
        "contentType": "author"
      }
    }
  },
  "meta": {
    "id": "314159265358979323",
    "contentType": "poem",
    "repository": "123456789011121415",
    "revision": 1,
    "tags": [],
    "createdAt": "2018-01-01T00:00:00.000Z",
    "updatedAt": "2018-01-01T00:00:00.000Z"
  }
}
],
includes: [
  author: [
    {
      "fields": {
        "name": "Victor Hugo"
      },
      "meta": {
        "id": "323979853562951413",
        "contentType": "author",
        "repository": "123456789011121415",
        "revision": 1,
        "tags": [],
        "createdAt": "2018-01-01T00:00:00.000Z",
        "updatedAt": "2018-01-01T00:00:00.000Z"
      }
    }
  ]
]

```

{% endtab %}
{% endtabs %}

If you just want to include the relations from a single or multiple **specific fields**, you can define these fields in your query.

#### Notation

The notation for fields is similar to filters. You can either include a `contentType` as field prefix, or a wildcard (\*).

```http
includes[<contentType>.fields.<fieldName>]=1
```

or

```http
includes[*.fields.<fieldName>]=1
```

To query multiple levels (relation of a relation...) with the field syntax, fields can be chained:

```http
includes[<contentType>.fields.<fieldName>.fields.<fieldName>]=1
```

## Field types

Field types which contain references are the following:

* `relation field`
* `asset field`

## Embed Assets

From a technical perspective, assets are relations and by default they are treated like that.

But sometimes assets, for example images, can be seen as a piece of content that you want to be included within a document field. For this case, you can use the `embedAssets` parameter.

#### Notation

```
embedAssets=true
```

## Examples

Find some examples on the includes example page:

{% content-ref url="/pages/-LEUdHv6HXaSTZ4NHr0P" %}
[Includes](/apis/rest-api/examples/includes.md)
{% endcontent-ref %}