# Reference

## REST resources

### Dashboard registration

Dashboard registration endpoints let you manage dashboards and where they are displayed. Those endpoint usually take or return [DashboardRegistration](#dashboardregistration) objects.

## List all dashboard registrations for a specific organisation

<mark style="color:blue;">`GET`</mark> `https://api.mediarithmics.com/v1/dashboards?organisation_id=:organisation_id`

Returns a [paginated resource list wrapper](/resources/api-overview.md#resource-list-wrapper-paginated-apis) of [DashboardRegistration](#dashboardregistration) objects.

## Create a dashboard registration.

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

Receives a [DashboardRegistration](#dashboardregistration) object as body.

## Edit a dashboard registration

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

Receives a [DashboardRegistration](#dashboardregistration) object as body.

## Get a specific dashboard registration

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

Returns a [DashboardRegistration](#dashboardregistration) object.

## Delete a dashboard registration

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

### Dashboard content

Dashboard content endpoints let you manage the sections, cards and charts in a specific dashboard.

## Get the content of a dashboard. Returns a DashboardContentWrapper.

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

## Edit the content of a dashboard with the specified DashboardContent.

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

## DashboardRegistration

This object represents a dashboard and where it should be displayed.

{% code title="JSON representation" %}

```json5
{
    "title": String,
    "scopes": [Scope]
    "segment_ids": [String],
    "builder_ids": [String],
    "archived": Boolean,
    "dashboard_content_id": String,
    "organisation_id": String,
    "community_id": String,
    // Readonly fields
    "created_ts": Timestamp,
    "created_by": String,
    "last_modified_ts": Timestamp,
    "last_modified_by": String
}
```

{% endcode %}

#### Fields

`title` **string**

The title of the dashboard, as displayed in the UI

`scopes[]` **enum(`home`,`segments`,`builders`)**

The list of scopes where the dashboard is visible. Mandatory, but can be an empty array.

`segment_ids[]` **string**

When `scopes`  property contains `segments`, you can specify a list of segment IDs to only display the dashboard on those specific segments. Mandatory, but can be an empty array.

`builder_ids[]` **string**

When `scopes`  property contains `builders`, you can specify a list of standard segment builder IDs to only display the dashboard on those specific builders. Mandatory, but can be an empty array.

`archived` **boolean**

Set to `true` to hide a dashboard from the UI without deleting it.

`dashboard_content_id` **string**

Identifier of the [DashboardContentWrapper](#dashboardcontentwrapper) that's been associated with the dashboard registration.

`community_id` **string**

ID of the community on which the dashboard is visible.

`organisation_id` **string**

ID of the organisation on which the dashboard is visible. Must be on the `community_id` community.

`created_ts` **timestamp**

When the dashboard registration was created. **ReadOnly**.

`created_by` **user ID**

By who the dashboard registration was created. **ReadOnly**.

`last_modified_ts` **timestamp**

When the dashboard registration was last modified. Not updated when dashboard content is updated as DashboardContent object has its own `created_ts` field.  **ReadOnly**.

`last_modified_by` **user ID**

By who the dashboard was last modified. Not updated when dashboard content is updated as DashboardContent object has its own `created_by` field. **ReadOnly**.

## DashboardContentWrapper

This object is returned when doing a `GET` request to get the content of a dashboard. It returns useful metadata as well as dashboard's content

{% code title="JSON representation" %}

```json5
{
    "id": String,
    "content": DashboardContent
    "organisation_id": String,
    "created_ts": Timestamp,
    "created_by": String
}
```

{% endcode %}

#### Fields

`id` **string**

Content's identifier, used in [DashboardRegistration](#dashboardregistration) to associate a dashboard and its content.

`content` **object(**[**DashboardContent**](#dashboardcontent)**)**

Dashboard's JSON representation.

`organisation_id` **string**

ID of the organisation on which the dashboard is visible.&#x20;

`created_ts` **timestamp**

When the dashboard content was created. **ReadOnly**.

`created_by` **user ID**

By who the dashboard content was created. **ReadOnly**.

{% hint style="info" %}
Each time you do a PUT request to update a dashboard's content, a new `DashboardContentWrapper` resource is created with a new ID, and the new resource is associated with the dashboard registration. That means the `created_ts` and `created_by` fields also represent the `last_modified_ts` and `last_modified_by` fields you are used to see.
{% endhint %}

## DashboardContent

This object represents the sections, cards and charts displayed in a dashboard.

{% code title="JSON representation" %}

```json5
{
    "available_filters": [Filter]
    "sections": [Section]
}
```

{% endcode %}

`available_filters[]` **object(**[**Filter**](#filter)**)**

The list of filters activated for the dashboard.

`sections[]` **object(**[**Section**](#section)**)**

The list of sections inside a dashboard.

## Filter

A filter is displayed at the top of a dashboard. The user can select a value and all the queries in the dashboard adapt to the selected value

{% code title="JSON representation" %}

```json5
{
    // Using technical names of compartments, segments or channels 
    // will result in IDs being automatically replaced by names in the UI
    "technical_name": String, 
    "title": String,
    "values_retrieve_method": 'Query', // Only available value at the moment
    // OTQL query to retrieve list of selectable values
    // Use a query string, not the ID of a query
    "values_query": String, 
    // How to adapt queries in the dashboard to the selected value(s)
    "query_fragments": [QueryFragment], 
    "multi_select": Boolean, // If the user can select multiple values
}
```

{% endcode %}

A query fragment tells the dashboard how to adapt each query to the value(s) selected by the user.

{% code title="JSON representation" %}

```json5
{
    // Any available data source such as 'activities_analytics' or 'OTQL'
    "type": String, 
    // Only for OTQL type, chooses which queries should be transformed
    // Select 'ActivityEvent' to transform queries FROM ActivityEvent
    "starting_object_type": String,
    // The query part to add 
    "fragment": String,
}
```

{% endcode %}

## Section

A section gives you a title and a new grid to display cards.

{% code title="JSON representation" %}

```json5
{
    "title": String,
    "cards": [Card],
}
```

{% endcode %}

`title` **string**

The title of the section, displayed in the UI.

`cards[]` **object(**[**Card**](#card)**)**

The list of cards to display in the section.

## Card

A white zone in the section, that displays and organizes charts.

{% code title="JSON representation" %}

```json5
{
    "x": Int,
    "y": Int,
    "h": Int,
    "w": Int,
    "layout": "vertical" || "horizontal",
    "charts": [Chart],
}
```

{% endcode %}

`x,y,h,w` **int**

The position of the card in the section's grid. See [Sections, cards and charts](/dashboards/sections-and-cards.md) for a guide on how to use it.

`layout` **enum(`vertical`, `horizontal`)**

Wether charts in the card will stack horizontally or vertically.

`charts[]` **object(**[**Chart**](#chart)**)**

The list of charts to display in the card.

## Chart

A chart displayed in a card.

{% code title="JSON representation" %}

```json5
 {
    "title": String,
    "type": "Pie" || "Bars" || "Radar" || "Metric" || "Area", 
    "dataset": Dataset,
    "options": PieOptions || BarsOptions || RadarOptions || MetricOptions || AreaOptions
}
```

{% endcode %}

`title` **string**

The chart's title, displayed in the UI.

`type` **enum(`Pie`, `Bars`, `Radar`, `Metric`)**

The type of chart to display

`colors[]` **string**

*Optional*. You can use this property to override default chart colors, which are defined by the theme of the site. Define as many color codes (in `#FFFFFF` format) as needed by the chart.

`dataset` **object(Dataset)**

How to get data for the chart

`options` **object(**[**`PieOptions`**](/dashboards/charts.md#pie-charts)**,** [**`BarsOptions`**](/dashboards/charts.md#bars-charts)**,** [**`RadarOptions`**](/dashboards/charts.md#radar-charts)**,** [**`MetricOptions`**](/dashboards/charts.md#metric-charts)**,** [**`AreaOptions`**](/dashboards/charts.md#area-charts)**)**

*Optional*. Options specific to the type of chart that has been selected.

{% hint style="info" %}

* For more information on the different chart types and there options, see [Charts](/dashboards/charts.md).
* For more information on how datasets are built, see [Datasets and data sources](/dashboards/datasets-and-data-sources.md).
  {% endhint %}


---

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