# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.comfortable.io/apis/rest-api/filters/includes.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.