Links
Comment on page

Reference

REST resources

Dashboard registration

Dashboard registration endpoints let you manage dashboards and where they are displayed. Those endpoint usually take or return DashboardRegistration objects.
get
https://api.mediarithmics.com/v1
/dashboards?organisation_id=:organisation_id
List all dashboard registrations for a specific organisation
post
https://api.mediarithmics.com/v1
/dashboards
Create a dashboard registration.
put
https://api.mediarithmics.com/v1
/dashboards/:id?organisation_id=:organisation_id
Edit a dashboard registration
get
https://api.mediarithmics.com/v1
/dashboards/:id?organisation_id=:organisation_id
Get a specific dashboard registration
delete
https://api.mediarithmics.com/v1
/dashboards/:id?organisation_id=:organisation_id
Delete a dashboard registration

Dashboard content

Dashboard content endpoints let you manage the sections, cards and charts in a specific dashboard.
get
https://api.mediarithmics.com/v1
/dashboards/:id/content?organisation_id=:organisation_id
Get the content of a dashboard. Returns a DashboardContentWrapper.
put
https://api.mediarithmics.com/v1
/dashboards/:id/content?organisation_id=:organisation_id
Edit the content of a dashboard with the specified DashboardContent.

DashboardRegistration

This object represents a dashboard and where it should be displayed.
JSON representation
{
"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
}

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 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
JSON representation
{
"id": String,
"content": DashboardContent
"organisation_id": String,
"created_ts": Timestamp,
"created_by": String
}

Fields

id string
Content's identifier, used in DashboardRegistration to associate a dashboard and its content.
content object(DashboardContent)
Dashboard's JSON representation.
organisation_id string
ID of the organisation on which the dashboard is visible.
created_ts timestamp
When the dashboard content was created. ReadOnly.
created_by user ID
By who the dashboard content was created. ReadOnly.
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.

DashboardContent

This object represents the sections, cards and charts displayed in a dashboard.
JSON representation
{
"available_filters": [Filter]
"sections": [Section]
}
available_filters[] object(Filter)
The list of filters activated for the dashboard.
sections[] object(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
JSON representation
{
// 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
}
A query fragment tells the dashboard how to adapt each query to the value(s) selected by the user.
JSON representation
{
// 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,
}

Section

A section gives you a title and a new grid to display cards.
JSON representation
{
"title": String,
"cards": [Card],
}
title string
The title of the section, displayed in the UI.
cards[] object(Card)
The list of cards to display in the section.

Card

A white zone in the section, that displays and organizes charts.
JSON representation
{
"x": Int,
"y": Int,
"h": Int,
"w": Int,
"layout": "vertical" || "horizontal",
"charts": [Chart],
}
x,y,h,w int
The position of the card in the section's grid. See Sections, cards and charts 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)
The list of charts to display in the card.

Chart

A chart displayed in a card.
JSON representation
{
"title": String,
"type": "Pie" || "Bars" || "Radar" || "Metric" || "Area",
"dataset": Dataset,
"options": PieOptions || BarsOptions || RadarOptions || MetricOptions || AreaOptions
}
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
Optional. Options specific to the type of chart that has been selected.
  • For more information on the different chart types and there options, see Charts.
  • For more information on how datasets are built, see Datasets and data sources.