# Metadata

## Introduction

mitter.io allows attaching metadata to certain entities. Currently, **Channels** and **Users** are supported.

The examples below demonstrate operations with Channels, but the same can be performed on Users as well (by replacing "channels" in the URLs with "users", and providing the `userId` instead of the `channelId`)

Here is a sample API call to `POST` metadata:

```
POST /v1/channels/my-awesome-channel/metadata
{
    "type": "awesome-channel",
    "maxParticipants": 256,
    "meetingLocation": {
        "latitude": 12,
        "longitude": 12
    }
}
```

You can query Channels by metadata like so:

```
GET /v1/channels?metadata={type:"awesome-channel"}
```

NOTE: The URL in the example is not encoded for readability's sake, but it must be when making actual calls.

## Behaviour

Metadata can be any valid JSON and adheres to the following rules:

1. The top level values of the JSON (in the above case, "awesome-channel", 256, and the location JSON) can only be string, numeric or JSON. It cannot be boolean.
2. Only top level keys can be used to query objects. For instance, in the above example, you can query Channels by `type, maxParticipants` and `meetingLocation,` but **NOT** by `meetingLocation.latitude.`
3. If you `POST` metadata with a key that already exists, it will be overridden. Keys with JSON values will not be merged.
4. When querying entities, you can specify multiple JSON, and all entities that match **ALL** queries will be fetched, i.e., if you provide multiple queries, the system will do an AND operation. For instance, if you execute `GET /v1/channels?metadata={type: "awesome-channel", "age": 2}`, then you will NOT get the above channel. Similarly, if you have two channels:

```
{
    "channelId": "channel-one",
    ...
    "metadata": {
        "type": "business",
        "area": "IN"
    }
}

{
    "channelId": "channel-two",
    ...
    "metadata": {
        "type": "business",
        "area": "EU"
    }
}
```

and you try to execute `GET /v1/channels?metadata={type: "business"}`, then the response will be `channel-one`


---

# 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.mitter.io/platform-reference-1/metadata.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.