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.

List all dashboard registrations for a specific organisation

GET https://api.mediarithmics.com/v1/dashboards?organisation_id=:organisation_id

Returns a paginated resource list wrapper of DashboardRegistration objects.

Create a dashboard registration.

POST https://api.mediarithmics.com/v1/dashboards

Receives a DashboardRegistration object as body.

Edit a dashboard registration

PUT https://api.mediarithmics.com/v1/dashboards/:id?organisation_id=:organisation_id

Receives a DashboardRegistration object as body.

Get a specific dashboard registration

GET https://api.mediarithmics.com/v1/dashboards/:id?organisation_id=:organisation_id

Returns a DashboardRegistration object.

Delete a dashboard registration

DELETE 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.

GET https://api.mediarithmics.com/v1/dashboards/:id/content?organisation_id=:organisation_id

Edit the content of a dashboard with the specified DashboardContent.

PUT https://api.mediarithmics.com/v1/dashboards/:id/content?organisation_id=:organisation_id

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

options object(PieOptions, BarsOptions, RadarOptions, MetricOptions, AreaOptions)

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.