> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getmateo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Resource Embedding

> Our API supports including related resources in a single API call. This reduces the need for many API requests.

<Warning>
  This is an advanced feature. Only start using it if you are comfortable with
  our API.
</Warning>

## Many-to-One Relationships

Since a `message` always has a `conversation`, they have a many-to-one relationship. This enables us to request all the messages and the conversation for each message.

```bash theme={null}
curl "https://integration.getmateo.com/api/v1/message?select=id,conversation(subject)"
```

```json theme={null}
[
  {
    "id": 1,
    "conversation": {
      "subject": "Hello"
    }
  },
  {
    "id": 2,
    "conversation": {
      "subject": "Goodbye"
    }
  }
]
```

Note that the embedded `conversation` is returned as a JSON object because of the “to-one” end.

## One-to-Many Relationships

The foreign key reference establishes the inverse one-to-many relationship. In this case, message returns as a JSON array because of the “to-many” end.

```bash theme={null}
curl "https://integration.getmateo.com/api/v1/conversation?select=id,subject,messages(id)"
```

```json theme={null}
[
  {
    "id": 1,
    "subject": "Hello",
    "messages": [
      {
        "id": 1
      },
      {
        "id": 2
      }
    ]
  },
  {
    "id": 2,
    "subject": "Goodbye",
    "messages": [
      {
        "id": 3
      }
    ]
  }
]
```

## Many-to-Many Relationships

In this example, a `conversation` has `tag`s assigned via a `conversation_tag` relation. This is a many-to-many relationship.

```bash theme={null}
curl "https://integration.getmateo.com/api/v1/conversation?select=id,subject,tag(name)"
```

```json theme={null}
[
  {
    "id": 1,
    "subject": "Hello",
    "tag": [
      {
        "name": "greeting"
      },
      {
        "name": "important"
      }
    ]
  },
  {
    "id": 2,
    "subject": "Goodbye",
    "tag": [
      {
        "name": "farewell"
      }
    ]
  }
]
```