Report Template¶
Endpoints
GET /report_templates
GET /report_templates/:id
POST /report_templates
PUT /report_templates/:id
DELETE /report_templates/:id
DELETE /report_templates
A report template is a set of reporting widgets that are able to calculate, visualize and aggregate analytics based on a portfolio and/or datastores.
The report template object¶
What a report template object looks like?
{
"version": "v1",
"status": "OK",
"updated": 1624633635,
"name": "My First Report Template",
"tags": ["first", "new", "report_template"],
"created": 1624633635,
"workspace": "main",
"id": "rtpl_UHAo64xdlah3iR9lZgB6LFwAb",
"categories": [],
"description": "Design a custom report using Everysk's library of widgets and analytics. #blank #new #report"
}
| Property | Description |
|---|---|
id string |
Unique identifier (UID) for the report template. |
created timestamp |
Time at which the object was created. Measured in seconds since the Unix epoch. |
updated timestamp |
Time at which the object was updated. Measured in seconds since the Unix epoch. |
name string |
The report template's name. |
description string |
An arbitrary string attached to the report template. Default is "". |
tags array |
A list of strings. Up to 32 tags. Use them to find the report template with a query. |
status string |
The status of the report template, for example OK. |
version string |
Indicates the report template's current version. |
categories array |
The report template categories. Up to 3. |
layout array |
The widgets of the report template. Only included when with_layout is True. |
global_parameters object |
The parameters that every widget of the report template uses. Only included when with_layout is True. |
workspace string |
The workspace where the report template was generated. |
List all Report Templates¶
Returns a list of report templates you’ve previously generated. The report templates are returned in sorted order, with the most recent report template appearing first.
To list all report templates, run the following:
The above call returns the following JSON object:
{
"report_templates": [
{
"status": "OK",
"updated": 1632329105,
"name": "First Report Template",
"tags": ["first", "new", "report_template"],
"created": 1630348524,
"workspace": "main",
"id": "rtpl_oobGe082N8U4PPhLrU60xNOLT",
"categories": [],
"description": "Design a custom report using Everysk's library of widgets and analytics. #blank #new #report"
},
{
"status": "OK",
"updated": 1627663323,
"name": "Second Report Template",
"tags": ["blank", "new", "report"],
"created": 1627593196,
"workspace": "main",
"id": "rtpl_oZbdHf786RRZIGN3WJQSY2M88",
"categories": [],
"description": "Design a custom report using Everysk's library of widgets and analytics. #blank #new #report"
}
],
"next_page_token": null
}
HTTP Request
GET /report_templates
HTTP Parameters
| Parameter | Description |
|---|---|
query string |
optional, default is null Request a list of report templates filtering it by name or tag. When using a tag to perform a query, each term must include a hashtag prefix. (e.g: query="#april #sample") |
page_size int |
optional, default is 10 Set the number of objects that will be listed per page. |
page_token string |
optional, default is null The next_page_token from the previous response. See the pagination guide. |
workspace string |
optional, default is main The workspace to list. |
with_layout boolean |
optional, default is False When True, each report template in the list includes its layout and global_parameters. |
Retrieve a report template¶
Retrieves the details of an existing report template by supplying the report template's id.
To retrieve a report template, run the following:
The above call returns the following JSON object:
{
"report_template": {
"status": "OK",
"updated": 1624633635,
"layout": [
...
],
"description": "Design a custom report using Everysk's library of widgets and analytics. #blank #new #report",
"created": 1624633635,
"tags": [
"first",
"new",
"report_template"
],
"workspace": "main",
"global_parameters": {
"advanced_settings": {
"confidence": {
"variant": "select",
"select": {
"value": "95%",
"label": "95%"
}
},
"correlation_half_life": {
"variant": "select",
"select": {
"value": 6,
"label": "6-months"
}
}
...
}
},
"id": "rtpl_UHAo64xdlah3iR9lZgB6LFwAb",
"categories": [],
"name": "First Report Template"
}
}
HTTP Request
GET /report_templates/:id
HTTP Parameters
| Parameter | Description |
|---|---|
id string |
REQUIRED A unique identifier (UID) for a report template. A report template's id will always look like this: rtpl_UHAo64xdlah3iR9lZgB6LFwAb. |
workspace string |
optional The workspace of the object. If you send it and the object is in another workspace, the API returns 403. |
with_layout boolean |
optional, default is True When True, the response includes layout and global_parameters. |
Create a report template¶
Creates a report template and then returns it. The layout and global_parameters have the format that retrieve returns. The easiest way to build them is to copy them from an existing report template.
To copy the layout of an existing report template into a new report template, run the following:
template=$(curl -s "https://api.everysk.com/v2/report_templates/rtpl_UHAo64xdlah3iR9lZgB6LFwAb" \
-H "Authorization: Bearer <ACCESS_TOKEN>" | jq '.report_template')
curl https://api.everysk.com/v2/report_templates \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-d "$(echo "$template" | jq '{
name: "My Second Report Template",
description: "A copy of my first report template.",
tags: ["second", "report_template"],
workspace: "main",
layout, global_parameters
}')" \
-X POST
This example relies on jq to read and build the JSON. The call returns the new report template, in the same format as retrieve.
HTTP Request
POST /report_templates
HTTP Parameters
| Parameter | Description |
|---|---|
name string |
REQUIRED The report template's name. 1 to 200 characters. |
layout array |
REQUIRED The widgets of the report template. Each item has a type. Up to 150 widgets and 150 items of type offsetCol. |
global_parameters object |
REQUIRED The parameters that every widget of the report template uses. |
description string |
optional, default is "" An arbitrary string attached to the report template. Up to 500 characters. |
tags array |
optional, default is [] A list of strings. Up to 32 tags. |
categories string |
optional, default is "" The categories of the report template, separated by commas. Up to 3. |
with_layout boolean |
optional, default is True When True, the response includes layout and global_parameters. |
workspace string |
optional, default is main The workspace where the API creates the report template. Send it in the JSON body. |
Update a report template¶
Replaces a report template and then returns it. The update is not partial: send name, layout and global_parameters every time, or the API returns 400. A field that you leave out goes back to its default value, the same as on create. This also applies to workspace: if you leave it out, the API moves the report template to main.
To rename a report template and keep the rest of it, run the following:
template=$(curl -s "https://api.everysk.com/v2/report_templates/rtpl_UHAo64xdlah3iR9lZgB6LFwAb" \
-H "Authorization: Bearer <ACCESS_TOKEN>" | jq '.report_template')
curl https://api.everysk.com/v2/report_templates/rtpl_UHAo64xdlah3iR9lZgB6LFwAb \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-d "$(echo "$template" | jq '{
name: "My Renamed Report Template",
description, tags, workspace, layout, global_parameters,
categories: (.categories | join(","))
}')" \
-X PUT
The call returns the updated report template, in the same format as retrieve.
HTTP Request
PUT /report_templates/:id
HTTP Parameters
| Parameter | Description |
|---|---|
id string |
REQUIRED A unique identifier (UID) for a report template. |
name string |
REQUIRED The report template's name. |
layout array |
REQUIRED The widgets of the report template. |
global_parameters object |
REQUIRED The parameters that every widget of the report template uses. |
workspace string |
optional, default is main Moves the report template to this workspace. If you leave it out, the API moves the report template to main. To keep it where it is, send its current workspace. |
| Others | description, tags, categories and with_layout, with the same rules and defaults as on create. |
Delete a report template¶
To delete a report template, run the following:
The above call returns the following JSON object:
{
"report_template": {
"deleted": true,
"id": "rtpl_UHAo64xdlah3iR9lZgB6LFwAb",
"name": "First Report Template"
}
}
Permanently deletes a report template. It cannot be undone. Returns an object with the report template's id, its name and an attribute specifying whether the report template was successfully deleted or not.
HTTP Request
DELETE /report_templates/:id
HTTP Parameters
| Parameter | Description |
|---|---|
id string |
REQUIRED A unique identifier (UID) for a report template. |
workspace string |
optional The workspace of the object. If you send it and the object is in another workspace, the API returns 403. |
Delete several report templates¶
To delete several report templates in one call, leave the id out of the path and send the ids in ids, separated by commas: DELETE /report_templates?ids=<id>,<id>. The response has a report_templates array with one {"id", "name", "deleted"} object per id. An id that the API does not find gives null. If you send workspace and a report template is in another workspace, the API returns 403 and deletes none.
HTTP Request
DELETE /report_templates
HTTP Parameters
| Parameter | Description |
|---|---|
ids string |
REQUIRED The ids of the report templates, separated by commas. |
workspace string |
optional The workspace of the report templates. |