Report¶
Endpoints
POST /reports/synchronous
GET /reports
POST /reports/filter
GET /reports/:id
PUT /reports/:id
POST /reports/:id/share
POST /reports/:id/email
DELETE /reports/:id
DELETE /reports
Interactive dashboards that present portfolio analytics information in an intuitive and explorable way. Reports represent a specific portfolio and date so that they can be referenced in the future.
The report object¶
What a report object looks like?
{
"updated": 1624633602,
"name": "My First Report",
"relative_url": "/report/f46906305657494f9e6bd25e0dcae769",
"tags": ["first", "report", "20210622"],
"url": "https://app.everysk.com/report/f46906304787494f9e6bd25e0dcae769",
"absolute_url": "https://app.everysk.com/report/f46906304787494f9e6bd25e0dcae769",
"created": 1624633585,
"workspace": "preview",
"id": "repo_KqbStPc7x2m5GW1GWKZCVlzPM",
"authorization": "private",
"description": "This is my first report."
}
| Property | Description |
|---|---|
id string |
Unique identifier (UID) for the report. |
created timestamp |
Time at which the object was created, measured in seconds since the Unix epoch. |
updated timestamp |
Time at which the object was last updated, measured in seconds since the Unix epoch. |
name string |
The report's name. |
description string |
An arbitrary string attached to the report. Default is "". |
tags array |
A list of strings. Up to 32 tags. Use them to find the report with a query. |
version string |
Indicates the report's current version. |
date string |
Report date in the format YYYYMMDD. The Report Date instructs the API to use the market conditions and security prices prevailing on that date. To run the report using today’s conditions, use null. |
widgets array |
The widgets of the report, each with its id, name and URLs. Lists leave it out unless you send with_widgets=true. |
authorization string |
Indicates whether the report is public or private. |
link_uid string |
An identifier you set to link the report to an external system. Default is null. |
url string |
The web address where the report can be accessed. |
absolute_url string |
The absolute web address where the report can be accessed. |
relative_url string |
The relative endpoint where the report can be accessed. |
workspace string |
The workspace in which the report was generated. |
Create a report¶
To create a new report, run the following:
curl https://api.everysk.com/v2/reports/synchronous \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-d '{
"name": "My First Report",
"description": "This is my first report",
"tags": ["first", "report", "20210622"],
"date": "20210622",
"workspace": "main",
"custom_settings": {},
"custom_widgets": [
{
"widgetType": "text",
"widgetTitle": "Summary",
"row": 0,
"col": 12,
"aspectRatio": "4:1",
"textModel": {
"is_primitive": true,
"text_title": null,
"text_content": "<p>Risk summary of the fund.</p>",
"text_align": "left",
"text_is_html": true
}
}
]
}' \
-X POST
The above call returns the following JSON object:
{
"report": {
"updated": 1624633585,
"name": "My First Report",
"relative_url": "/report/f46906305657494f9e6bd25e0dcae769",
"tags": ["first", "report", "20210622"],
"url": "https://app.everysk.com/report/f46906305657494f9e6bd25e0dcae769",
"absolute_url": "https://app.everysk.com/report/f46906305657494f9e6bd25e0dcae769",
"created": 1624633585,
"workspace": "main",
"widgets": null,
"id": "repo_KqbStPc7x2m5GW1GWKZCVlzPM",
"authorization": "private",
"description": "This is my first report",
"date": "20210622",
"link_uid": null
}
}
Creates a report from a list of widgets and then returns it. The API builds each widget before it answers, so the call can take some time. The path is /reports/synchronous: POST /reports returns 404.
The new report is always private. The API does not use the authorization that you send. To make the report public, use update after you create it.
HTTP Request
POST /reports/synchronous
HTTP Parameters
| Parameter | Description |
|---|---|
name string |
REQUIRED The report's name. Up to 200 characters. |
description string |
optional, default is null An arbitrary string attached to the report. Up to 500 characters. |
tags array |
optional, default is [] A list of strings. Up to 32 tags. |
date string |
optional, default is null (today) Report date in the format YYYYMMDD. |
custom_widgets array |
REQUIRED The widgets of the report. See Report widgets. Without widgets, the call fails. |
custom_settings object |
optional, default is null The calculation settings of all the widgets. See Report settings. The API keeps only the keys that it knows and drops other keys. A widget can override them in its own userSettings. |
workspace string |
optional, default is main The workspace where the API creates the report. Send it in the JSON body. |
link_uid string |
optional, default is null An identifier you set to link the report to an external system. |
with_widgets boolean |
optional, default is False When True, the response includes the widgets of the report. |
Report widgets¶
Each item of custom_widgets is one widget. The API puts the widgets that have the same row in one row, and shows the rows in the order of row.
| Property | Description |
|---|---|
widgetType string |
REQUIRED The type of the widget: text, title, date, image, file, customTable, customCell, customNVD3Chart, customApexChart, trades, relativeTrades, stressTest or offsetCol (an empty space). The API shows a widget of another type as an empty space. |
row integer |
The row of the widget. Default is 0. |
col integer |
The width of the widget, in columns. For offsetCol, the width of the empty space. |
widgetTitle string |
The title of the widget. |
widgetLink string |
A link on the widget. Default is "". |
tickerFilter string |
A filter of the portfolio securities that the widget uses. Default is null. |
aspectRatio string |
The width and the height of the widget, in the format W:H (for example 16:9), or auto. Default is 16:9. |
autoHeight boolean |
When True, the widget height follows its content. Default is False. |
collapsed boolean |
When True, the widget shows collapsed. Default is False. |
userSettings object |
The calculation settings of this widget. It has the same keys as custom_settings and overrides them. Only trades uses them. |
The other properties of a widget depend on its type. See Widget types. The API drops a property that is not in these tables. The Report Generator worker makes these widgets from the layout of a report template.
A model object in a widget, such as textModel, must have "is_primitive": true. Without it, the API uses the default model and ignores the object that you send. A widget does not calculate its data: the chart, table, cell and stress test widgets show the data that you send in the model. If the API cannot build a widget, the call fails.
Widget types¶
widgetType |
What it shows | Properties |
|---|---|---|
text |
A block of text. | textModel object with text_title string, text_content string, text_align string (for example left or center) and text_is_html boolean. When text_is_html is True, the API removes the HTML tags that are not safe from text_content. |
title |
A title and a subtitle. | textModel object with text_title, text_subtitle, text_content, text_align, text_font and text_color, all string. |
date |
A date. | textModel object with date string (REQUIRED, ISO 8601, for example 2023-11-30), format string (a Python strftime format, for example %d/%m/%Y), text_align, text_font and text_color. |
image |
An image. | imageModel object with image_url string (REQUIRED, the url of a file) and image_margin integer. |
file |
A link to download a file. | fileModel object with file_url string (REQUIRED, the url of a file), file_name string and file_content_type string (the API selects the icon from it). |
customTable |
A table. | customTableModel object with custom_table object (REQUIRED, with headers array and rows array), action_label string, infoLabel string and hasWarning boolean. Without headers or rows, the widget shows "No data available". |
customCell |
One value. | customCellModel object with custom_cell object (REQUIRED) and has_warning boolean. |
customNVD3Chart |
A bar, line or waterfall chart. | customNVD3ChartModel object with custom_chart object. custom_chart has charts array, legend string (REQUIRED with charts), chart_colors, tooltip array, total_risk number, total_header, action_label string and hasWarning boolean. Each item of charts has type (for example bar, line or waterfall), data (a list of [x, y] pairs), and optional label, color, xFormat, yFormat, style and show_custom_tooltip. customChart is the old name of this type. |
customApexChart |
An ApexCharts chart. | customApexChartModel object with custom_apex_chart object (REQUIRED, the ApexCharts options, for example series, xaxis and yaxis). When xaxis.type is datetime, each item of series must have data as a list of [x, y] pairs. |
trades |
The positions of one portfolio. | portfolioID1 string (REQUIRED, the portfolio id), tradesDisplayType string (quantity or market_value, default is quantity), tradesRemoveErrors boolean (default is True: the widget leaves out the positions that do not have a valid status) and tickerFilter. To apply tickerFilter, the API calculates the aggregations of the portfolio with userSettings. |
relativeTrades |
The trades between two portfolios. | portfolioID1 string (REQUIRED, the old portfolio), portfolioID2 string (REQUIRED, the new portfolio), pivot string (the security property that matches the positions of the two portfolios, default is symbol) and tradesDisplayType (quantity or market_value, default is quantity). |
stressTest |
A stress test chart. | stressTestModel object with these keys, all REQUIRED: chartData array (8 items), globalDomain array ([min, max]), aggregation string, attributionModelLabel string, shockLabel string, chartColors object, selectedData integer, hasWarning boolean and settings array. |
offsetCol |
An empty space. | None. col sets the width. |
All the model objects also accept settings array: a list of {"name": ..., "value": ...} items that the widget shows as its settings, for example [{"name": "Periodicity", "value": "Daily"}].
Report settings¶
custom_settings sets the calculation settings of the report. The keys and their values are not the same as the calculation parameters. For example, confidenceLevel is 0.95, not 95%. The Report Generator worker sends these keys:
| Key | Description |
|---|---|
aggregationModel string |
How the API groups the positions, for example position or sector. Default is position. See Risk Aggregations. |
horizon integer |
The forecast horizon, in business days. Default is 5. See Simulation horizon. |
sampling integer |
The sampling rate of the historical returns, in business days. Default is 5. See Sampling combinations. |
volHalfLife integer |
The half life of the volatility, in months. Default is 2. See Exponential decay. |
corrHalfLife integer |
The half life of the correlation, in months. Default is 6. See Exponential decay. |
confidenceLevel number |
The confidence level, as a number, for example 0.95 for 95%. Default is 0.95. See Confidence. |
posteriorModel string |
probEntropy, probKernel or probCrisp: the entropy, kernel and crisp methods of Posterior model. Default is probEntropy. |
projectionModel object |
The factors of the model, with name, tickers and labels. Default is the US Equities projection. See Projection model. |
The API changes horizon, sampling, volHalfLife and corrHalfLife to integers. Only the trades widget uses these settings, when it has a tickerFilter. The other widget types show the data that you send.
List all reports¶
To list all reports, run the following:
The above call returns the following JSON object:
{
"reports": [
{
"updated": 1624633522,
"name": "My Second Report",
"relative_url": "/report/6870426745114f7cb17595be77bea64c",
"tags": ["second", "report", "20210622"],
"url": "https://app.everysk.com/report/6870426745114f7cb17595be77bea64c",
"absolute_url": "https://app.everysk.com/report/6870426745114f7cb17595be77bea64c",
"created": 1624633522,
"workspace": "main",
"id": "repo_N2wZOHGo5pbmhVwQT3UX2ifk4",
"authorization": "private",
"description": ""
},
{
"updated": 1624633602,
"name": "My First Report",
"relative_url": "/report/f46906305657494f9e6bd25e0dcae769",
"tags": ["first", "report", "20210622"],
"url": "https://app.everysk.com/report/f46906304787494f9e6bd25e0dcae769",
"absolute_url": "https://app.everysk.com/report/f46906304787494f9e6bd25e0dcae769",
"created": 1624633585,
"workspace": "main",
"id": "repo_KqbStPc7x2m5GW1GWKZCVlzPM",
"authorization": "private",
"description": ""
}
],
"next_page_token": null
}
Returns a list of reports you’ve previously generated. The reports are returned in sorted order, with the most recent report appearing first.
HTTP Request
GET /reports
HTTP Parameters
| Parameter | Description |
|---|---|
query string |
optional, default is null Request a list of reports 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") See Filter with query. |
workspace string |
optional, default is main The workspace to list. |
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. |
with_widgets boolean |
optional, default is False When True, each report in the list includes its widgets. |
start, end, date_time, period_field string |
optional Filter the list by a period. See Filter by period. |
Filter reports¶
To filter reports, run the following:
The above call returns the following JSON object:
{
"reports": [
{
"updated": 1624633602,
"name": "My First Report",
"relative_url": "/report/f46906305657494f9e6bd25e0dcae769",
"tags": ["first", "report", "20210622"],
"url": "https://app.everysk.com/report/f46906304787494f9e6bd25e0dcae769",
"absolute_url": "https://app.everysk.com/report/f46906304787494f9e6bd25e0dcae769",
"created": 1624633585,
"workspace": "main",
"id": "repo_KqbStPc7x2m5GW1GWKZCVlzPM",
"authorization": "private",
"description": ""
},
...
]
}
Returns the reports of one workspace that match every filter you send, up to limit. The response has no next_page_token.
HTTP Request
POST /reports/filter
HTTP Parameters
| Parameter | Description |
|---|---|
workspace string |
REQUIRED The workspace to search. Without it, the API returns 400. |
tags array |
optional, default is [] A list of strings. Returns the reports that have every one of these tags. |
link_uid string |
optional, default is null Returns the reports with this link_uid. |
start string |
optional, default is null Returns the reports from this day onward, in the format YYYYMMDD. |
end string |
optional, default is null Returns the reports up to this day, in the format YYYYMMDD. |
date_time string |
optional, default is null Returns the reports of one day, in the format YYYYMMDD. It replaces start and end. |
period_field string |
optional, default is date The property that start, end and date_time filter: date or updated_on. |
limit integer |
optional, default is 1 The maximum number of reports to return, between 1 and 10000. |
with_widgets boolean |
optional, default is False When True, each report includes its widgets. |
Retrieve a report¶
To retrieve a report, run the following:
The above call returns the following JSON object:
{
"report": {
"updated": 1624633522,
"name": "My First Report",
"relative_url": "/report/6870426745114f7cb17595be77bea64c",
"tags": ["first", "report", "20210622"],
"url": "https://app.everysk.com/report/6870426745114f7cb17595be77bea64c",
"absolute_url": "https://app.everysk.com/report/6870426745114f7cb17595be77bea64c",
"created": 1624633522,
"workspace": "main",
"widgets": [
{
"absolute_url": "https://app.everysk.com/widget/5a4b6fc49767400c9f1cdddd4cc31050",
"id": "5a4b6fc49767400c9f1cdddd4cc31050",
"relative_url": "/widget/5a4b6fc49767400c9f1cdddd4cc31050",
"name": "Portfolio Property"
}
],
"id": "repo_N2wZOHGo5pbmhVwQT3UX2ifk4",
"authorization": "private",
"description": "This is my first report!"
}
}
Retrieves the details of an existing report by supplying the report's id.
HTTP Request
GET /reports/:id
HTTP Parameters
| Parameter | Description |
|---|---|
id string |
REQUIRED A unique identifier (UID) for a report. A report's id will always look like this: repo_N2wZOHGo5pbmhVwQT3UX2ifk4. |
workspace string |
optional The workspace of the object. If you send it and the object is in another workspace, the API returns 403. |
with_widgets boolean |
optional, default is True When True, the response includes the widgets of the report. |
Update a report¶
To update a report, run the following:
The call returns the updated report, in the same format as retrieve.
Updates a report and then returns it. Only the fields that you send change. A field that you leave out keeps its current value.
HTTP Request
PUT /reports/:id
HTTP Parameters
| Parameter | Description |
|---|---|
id string |
REQUIRED A unique identifier (UID) for a report. |
name string |
optional The report's name. |
description string |
optional An arbitrary string attached to the report. |
tags array |
optional A list of strings. Up to 32 tags. |
date string |
optional Report date in the format YYYYMMDD. |
authorization string |
optional public or private. The API changes the value to lowercase. |
link_uid string |
optional An identifier you set to link the report to an external system. |
workspace string |
optional Moves the object to this workspace. Leave it out to keep the current workspace. |
Share a report¶
To share a report, run the following:
The above call returns the following JSON object:
{
"report": {
"id": "repo_N2wZOHGo5pbmhVwQT3UX2ifk4",
"name": "My First Report",
"description": "This is my first report",
"tags": ["first", "report", "20210622"],
"created": 1624633585,
"updated": 1624633602,
"workspace": "main",
"authorization": "private",
"url": "https://app.everysk.com/report/6870426745114f7cb17595be77bea64c/light",
"absolute_url": "https://app.everysk.com/report/6870426745114f7cb17595be77bea64c/light",
"relative_url": "/report/6870426745114f7cb17595be77bea64c/light",
"shared_url": "https://app.everysk.com/report/shared_TVRSaVltTXhZMkptTVRBeE5ETTNPV0V6TWpKbE1qaGpOVFEzTnpFMk9HRTZiV0U2LjE1NzQ4NjM2NjYuMDAwMDAwMzYwMC4yQnlFWFFsQUlnbjZmcTU0bjBRcUZWS2NxallDM3FnM3NXTTdOWmtNc2dz/light",
"url_token": "shared_TVRSaVltTXhZMkptTVRBeE5ETTNPV0V6TWpKbE1qaGpOVFEzTnpFMk9HRTZiV0U2LjE1NzQ4NjM2NjYuMDAwMDAwMzYwMC4yQnlFWFFsQUlnbjZmcTU0bjBRcUZWS2NxallDM3FnM3NXTTdOWmtNc2dz",
"expires_after": 3600,
"widgets": null,
"date": "20210622",
"date_time": "20210622 12:00:00",
"link_uid": null
}
}
Generates a url address where the report can be accessed.
HTTP Request
POST /reports/:id/share
HTTP Parameters
| Parameter | Description |
|---|---|
id string |
REQUIRED A unique identifier (UID) for a report. |
expires_after string |
optional, default is 1_hour The time until the shared url expires. It accepts 1_hour, 6_hours, 24_hours, 7_days, 30_days, 180_days or 360_days, or the same time in seconds (for example 3600). Other values return 400. The response gives it in seconds. |
skin_theme string |
optional, default is your user's theme (dark if not set) Sets the report's color theme. It accepts dark or light, in lowercase. Other values return 400. |
The share call does not read workspace.
Email a report¶
To send a shared report by email, run the following:
curl https://api.everysk.com/v2/reports/repo_N2wZOHGo5pbmhVwQT3UX2ifk4/email \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-d '{
"email_to": ["ana@example.com", "bob@example.com"],
"email_message": "This is the risk report of June.",
"url_token": "shared_TVRSaVltTXhZMkptTVRBeE5ETTNPV0V6TWpKbE1qaGpOVFEzTnpFMk9HRTZiV0U2LjE1NzQ4NjM2NjYuMDAwMDAwMzYwMC4yQnlFWFFsQUlnbjZmcTU0bjBRcUZWS2NxallDM3FnM3NXTTdOWmtNc2dz",
"expires_after": "1_hour"
}' \
-X POST
The above call returns the following JSON object:
{
"report": {
"id": "repo_N2wZOHGo5pbmhVwQT3UX2ifk4",
"name": "My First Report",
"description": "This is my first report",
"tags": ["first", "report", "20210622"],
"created": 1624633585,
"updated": 1624633602,
"workspace": "main",
"authorization": "private",
"url": "https://app.everysk.com/report/6870426745114f7cb17595be77bea64c/dark",
"absolute_url": "https://app.everysk.com/report/6870426745114f7cb17595be77bea64c/dark",
"relative_url": "/report/6870426745114f7cb17595be77bea64c/dark",
"widgets": null,
"date": "20210622",
"link_uid": null,
"status": "EMAIL_SENT"
},
"audit_log": {...}
}
Sends an email with the link of a shared report. First, share the report. Then send the url_token and the expires_after of the share response. The email has the name of the report, your name, your message, the link and the time until the link expires. The link uses the theme of your user.
When the email is sent, status is EMAIL_SENT. If the API cannot send the email, it returns 200 with an empty object ({}).
HTTP Request
POST /reports/:id/email
HTTP Parameters
| Parameter | Description |
|---|---|
id string |
REQUIRED A unique identifier (UID) for a report. |
email_to array |
REQUIRED The email addresses of the recipients. From 1 to 100 addresses. An address that is not valid returns 400. |
email_message string |
REQUIRED The message of the email. Up to 500 characters. It can be "". The email shows HTML as plain text. |
url_token string |
REQUIRED The url_token from the share response. A token of another report, or a token that does not match expires_after, returns 400. |
expires_after string |
optional, default is 1_hour The expires_after that you sent to the share call. It accepts the same values as the share call. |
The email call does not read workspace or skin_theme.
Delete a report¶
To delete a report, run the following:
The above call returns the following JSON object:
{
"report": {
"deleted": true,
"id": "repo_N2wZOHGo5pbmhVwQT3UX2ifk4",
"name": "My First Report"
}
}
Permanently deletes a report. It cannot be undone. Returns an object with the report's id, its name and an attribute specifying whether the report was successfully deleted or not.
HTTP Request
DELETE /reports/:id
HTTP Parameters
| Parameter | Description |
|---|---|
id string |
REQUIRED A unique identifier (UID) for a report. |
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 reports¶
To delete several reports in one call, leave the id out of the path and send the ids in ids, separated by commas. This call does not read workspace.
To delete several reports, run the following:
The above call returns the following JSON object:
{
"reports": [
{
"deleted": true,
"id": "repo_N2wZOHGo5pbmhVwQT3UX2ifk4",
"name": "BATCH_DELETE"
},
{
"deleted": true,
"id": "repo_KqbStPc7x2m5GW1GWKZCVlzPM",
"name": "BATCH_DELETE"
}
]
}
Each item has "name": "BATCH_DELETE". deleted is false only when the delete fails. An id that does not exist also gives "deleted": true.
HTTP Request
DELETE /reports
HTTP Parameters
| Parameter | Description |
|---|---|
ids string |
REQUIRED The ids of the reports, separated by commas. |