> For the complete documentation index, see [llms.txt](https://developer.mediarithmics.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.mediarithmics.io/dashboards/quickstart.md).

# Quickstart

{% hint style="success" %}
**You can manage charts using** [**the query tool**](https://userguides.mediarithmics.io/data-studio/query-tool) **and** [**edit dashboards in the UI**](https://userguides.mediarithmics.io/basics/dashboards/custom-dashboards#editing-dashboards-in-the-ui)**.** Manipulating dashboards by API and in advanced mode can be useful in some advanced integrations, but will take longer.
{% endhint %}

## Advanced mode

### Full dashboard edition

1. Run your query[ in the query tool](https://userguides.mediarithmics.io/data-studio/query-tool) and save it as a technical query. Note the ID of the query.
2. In the computing console, go to **dashboards** and add/edit a dashboard
3. Choose a name and save your dashboard. 
4. Switch to the **Advanced** tab.
5. Edit the JSON

See the [DashboardContent](/dashboards/reference.md#dashboardcontent) object for a quick reference.

<figure><img src="/files/Osd2QcrMeVm0jGBNwu1k" alt=""><figcaption><p>Dashboard advanced mode</p></figcaption></figure>

### Chart edition

1. Run your query[ in the query tool](https://userguides.mediarithmics.io/data-studio/query-tool) and save it as a technical query. Note the ID of the query.
2. In the computing console, go to **dashboards** and add/edit a dashboard
3. Add or edit a chart and go to the **Advanced** tab
4. Edit the JSON and preview your changes.

See the [Chart](/dashboards/reference.md#chart) object for a quick reference.

<figure><img src="/files/HV4GK6cLBRKeov8gmbQJ" alt=""><figcaption><p>Chart advanced mode</p></figcaption></figure>

## By API

### Step 1: Configure authentication

This quickstart guide uses the [Long term access tokens](/resources/api-overview/authentication.md#long-term-access-tokens) authentication method. Choose and configure your own authentication method. For more information, see [Authentication](/resources/your-first-integration/make-the-first-bulk-import/api-basics/authentication.md).

### Step 2 : Prepare the OTQL queries you will use on your dashboard

Your dashboard could use [OTQL queries](/querying-your-data/otql-queries.md) or [activities analytics queries](/querying-your-data/activities-analytics-queries.md) to retrieve data. We will use both in this tutorial, and OTQL queries need to be registered using the [Creating a query](/querying-your-data/otql-queries.md#managing-queries) endpoint.

## Creating a query

<mark style="color:green;">`POST`</mark> `https://api.mediarithmics.com/v1/datamarts/:datamartId/queries`

Register an OTQL query in the platform

We will create two OTQL queries for this tutorial. The first one counts the UserPoint in the datamart, the second one lists the devices they use.

{% hint style="info" %}
**For each query, note their ID.**

You should adapt those queries to your data model if required.
{% endhint %}

{% code title="BODY payload for query 1" %}

```json5
{
    "datamart_id": {{datamartId}},
    "query_language": "OTQL",
    "query_text": "select @count{} FROM UserPoint"
}
```

{% endcode %}

{% code title="BODY payload for query 2" %}

```json5
{
    "datamart_id": {{datamartId}},
    "query_language": "OTQL",
    "query_text": "SELECT {agents {user_agent_info{form_factor @map}}} FROM UserPoint"
}
```

{% endcode %}

### Step 3 : Create a dashboard registration

You first create a [DashboardRegistration](/dashboards/reference.md#dashboardregistration) object to reference your dashboard and define where it is visible.

## Create a dashboard registration

<mark style="color:green;">`POST`</mark> `https://api.mediarithmics.com/v1/dashboards`

Here is a sample body payload for a home dashboard with all the important properties

```json
{
    "title": "My awesome dashboards",
    "scopes": [
        "home"
    ],
    "segment_ids": [],
    "builder_ids": [],
    "archived": false,
    "organisation_id": "{{orgId}}",
    "community_id": "{{communityId}}"
}
```

### Step 4 : Put content in your dashboard

You can now upload content in your dashboard using the [DashboardContent](/dashboards/reference.md#dashboardcontent) object.

## Edit the content of a dashboard

<mark style="color:orange;">`PUT`</mark> `https://api.mediarithmics.com/v1/dashboards/:id/content?organisation_id=:organisation_id`

Here is a sample body payload for a content using the queries we previously created.

```json
{
    "sections": [
        {
            "title": "",
            "cards": [
                {
                    "x": 0,
                    "y": 0,
                    "h": 3,
                    "layout": "vertical",
                    "w": 8,
                    "charts": [
                        {
                            "title": "User points",
                            "type": "Metric",
                            "dataset": {
                                "type": "OTQL",
                                "query_id": "{{ID of query 1}}"
                            }
                        },
                        {
                            "title": "Device form factors",
                            "type": "Bars",
                            "dataset": {
                                "type": "OTQL",
                                "query_id": "{{ID of query 2}}"
                            },
                            "options": {}
                        }
                    ]
                }
            ]
        }
    ]
}
```

Go to your datamart's home page, and your dashboard is now displayed with the two charts we created !

&#x20;![](/files/dpfevFNxO3jO9Yiabm3O)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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://developer.mediarithmics.io/dashboards/quickstart.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.