Skip to content

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:

curl -G https://api.everysk.com/v2/report_templates \
  --data-urlencode "query=#first" \
  --data-urlencode "workspace=main" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

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:

curl "https://api.everysk.com/v2/report_templates/rtpl_UHAo64xdlah3iR9lZgB6LFwAb?workspace=main" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -G

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:

curl "https://api.everysk.com/v2/report_templates/rtpl_UHAo64xdlah3iR9lZgB6LFwAb?workspace=main" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -X DELETE

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.