Create a custom report using REST APIs¶
A Report has the following constructs
Container Folder
↳ Report
↳ Tab (aka Organizer)
↳ Widgets (aka reportcontents)
↳ COVERSHEET, TIMESERIES, SVD, LAYOUTNODEVIEW, OTHER
Step 1: First either create a folder or use and an existing folder of choice under the correct hierarchy
Step 2: Create an empty report in an existing folder
Step 3: Add a Tab (aka page or organizer) to the report. You may add multiple tabs as necessary
Step 4: Add a widget of choice to the Tab
Step 5: Place the widgets on the Tab
Step 1.1: Get Destination Folder ID¶
In this step, we will get the folder ID of the existing destination folder.
Request Parameters¶
folder name: Exact name of the destination folder
cURL request¶
$ curl --location --request GET 'https://app3.falkonry.ai/api/1.2/accounts/xxxxxxxxxxxxxx/layoutnodes?name=<folder name>&limit=1' \
--header 'Authorization: Bearer <roken>'
Python¶
import requests
URL = 'https://app3.falkonry.ai/api/1.2/accounts/xxxxxxxxxxxxxx/layoutnodes?name=<folder name>&limit=1'
TOKEN = '<token>'
HEADERS = {'Authorization': f'Bearer {TOKEN}'}
response = requests.get(URL, headers=HEADERS)
print (response.json())
Example response
- Use
folder name= Personal Reports to get the folder ID of the top-levelPersonal Reportscontainer folder - Use
folder name= Group Reports to get the folder ID of the top-levelGroup Reportscontainer folder
folder name = Child folder
[
{
"id": "1422656410257350656",
"name": "Child folder",
"layout": "1353851196958326784",
"layoutdefinition": "defaultDefinition",
"parent": "1422656276213272576",
"nodeType": "3",
"isRoot": false,
"path": [
{
"name": "Personal Reports",
"id": "1353851197247733760",
"seq": 1
},
{
"name": "Parent folder",
"id": "1422656276213272576",
"seq": 2
},
{
"name": "Child folder",
"id": "1422656410257350656",
"seq": 3
}
],
"materializedPath": "Personal Reports->Parent folder->Child folder",
"immediateSignalCount": 0,
"label": "labelnode",
"context": {
"variables": [
{
"name": "@report:layoutNode",
"type": "string",
"defaultValue": "FOLDER"
}
]
},
"layoutState": "DRAFT",
"layoutVersion": "1",
"type": "entities.layoutnodes",
"tenant": "xxxxxxxxxxxxxx",
"createTime": 1759258119883,
"updateTime": 1759260821902,
"createdBy": "596582102439518208",
"updatedBy": "596582102439518208",
"archived": false,
"nodeLevel": 3,
"links": []
}
]
Step 1.2: Create a Destination Folder ID¶
In this step, we will show how to create a report folder under an existing parent folder.
Request Parameters¶
folder name: Exact name of the destination folder
Request Payload¶
{
"context":{
"variables":[
{
"defaultValue":"FOLDER",
"name":"@report:layoutNode",
"type":"string"
}
]
},
"account":"xxxxxxxxxxxxxx",
"layout":"1353851196958326784",
"parent":"yyyyyyyyyyyyyyy",
"name":"<folder name>"
}
cURL request¶
$ curl --location --request POST 'https://app3.falkonry.ai/api/1.2/accounts/xxxxxxxxxxxxxxx/layoutnodes' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '<Insert Json payload here>'
Python¶
import requests
import json
URL = 'https://app3.falkonry.ai/api/1.2/accounts/xxxxxxxxxxxxxxx/layoutnodes'
TOKEN = '<token>'
HEADERS = {'Authorization': f'Bearer {TOKEN}', 'Content-Type': 'application/json'}
PAYLOAD = <Insert Json payload here>
response = requests.post(URL, headers=HEADERS, data=json.dumps(PAYLOAD))
print (response.json())
Example response
folder name = Test personal
{
"id": "1422675880791138304",
"name": "Test personal",
"layout": "1353851196958326784",
"layoutdefinition": "defaultDefinition",
"parent": "1353851197247733760",
"isRoot": false,
"path": [
{
"name": "Personal Reports",
"id": "1353851197247733760",
"seq": 1
},
{
"name": "Test personal",
"id": "1422675880791138304",
"seq": 2
}
],
"materializedPath": "Personal Reports->Test personal",
"immediateSignalCount": 0,
"label": "labelnode",
"context": {
"variables": [
{
"name": "@report:layoutNode",
"type": "string",
"defaultValue": "FOLDER"
}
]
},
"layoutState": "DRAFT",
"layoutVersion": "1",
"type": "entities.layoutnodes",
"tenant": "xxxxxxxxxxxxxxx",
"createTime": 1759262762020,
"updateTime": 1759262762020,
"createdBy": "596582102439518208",
"updatedBy": "596582102439518208",
"archived": false,
"nodeLevel": 2,
"links": []
}
Step 2: Create an Empty Report¶
In this step, we will create an empty report object to which we will subsequently add more details.
Request Parameters¶
account: Account IDname: Exact name for the reportdescription: Description of the reporttimezone: Timezone for the reportlayoutnode: Destination folder ID
Request Payload¶
{
"account":"xxxxxxxxxxxxxxx",
"layoutnode":"1422675880791138304",
"timeZone":"UTC",
"name":"Name of the report",
"description":"Report Description goes here."
}
Python¶
import requests
import json
URL = 'https://app3.falkonry.ai/api/1.2/accounts/xxxxxxxxxxxxxxx/reports'
TOKEN = '<token>'
HEADERS = {'Authorization': f'Bearer {TOKEN}', 'Content-Type': 'application/json'}
PAYLOAD = <Insert Json payload here>
response = requests.post(URL, headers=HEADERS, data=json.dumps(PAYLOAD))
print (response.json())
Example Response
{
"id": "1422678193744273408",
"type": "entities.report",
"tenant": "xxxxxxxxxxxxxxx",
"createTime": 1759263313471,
"updateTime": 1759263313471,
"createdBy": "596582102439518208",
"updatedBy": "596582102439518208",
"archived": false,
"name": "Name of the report",
"description": "Report Description goes here.",
"layoutinfo": [
{
"layout": "1353851196958326784",
"layoutnode": "1422675880791138304",
"version": "1",
"path": [
{
"name": "Personal Reports",
"id": "1353851197247733760",
"seq": 1
},
{
"name": "Test personal",
"id": "1422675880791138304",
"seq": 2
}
],
"materializedPath": "Personal Reports->Test personal",
"layoutState": "DRAFT",
"layoutname": "Report Hierarchy"
}
],
"spec": {
"variables": [
{
"name": "report:timeRange",
"type": "timeRange",
"value": [
"1422678193777827840",
"1422678193777827841"
]
}
]
},
"links": []
}
Step 3: Add a Tab to the Report¶
A Report needs a page (or Tab) to hold the report contents.
Request Parameters¶
name: Exact name for the Tabreport id: Destination report ID
Request Payload¶
{
"name": "Name of the tab",
"grid": []
}
Python¶
import requests
import json
URL = 'https://app3.falkonry.ai/api/1.2/accounts/xxxxxxxxxxxxxxx/reports/yyyyyyyyyyyyyyyy/organizers'
TOKEN = '<token>'
HEADERS = {'Authorization': f'Bearer {TOKEN}', 'Content-Type': 'application/json'}
PAYLOAD = <Insert Json payload here>
response = requests.post(URL, headers=HEADERS, data=json.dumps(PAYLOAD))
print (response.json())
Example Response
name: "Overview"report id: "yyyyyyyyyyyyyyyy"
{
"id": "1422678195992420352",
"type": "entities.organizer",
"tenant": "xxxxxxxxxxxxxxx",
"createTime": 1759263314007,
"updateTime": 1759263314007,
"createdBy": "596582102439518208",
"updatedBy": "596582102439518208",
"archived": false,
"report": "yyyyyyyyyyyyyyyy",
"name": "Overview",
"grid": [],
"links": []
}
Step 4: Add a Widget to the Report¶
The contents of a report are of multiple types, namely {COVERSHEET, TIMESERIES, SVD, LAYOUTNODEVIEW, OTHER}
Request Parameters¶
name: Exact name for the Tabreport id: Destination report ID
Request Payload¶
{
"name" : "Report Overview",
"contentType" : "COVERSHEET"
}
Python¶
import requests
import json
URL = 'https://app3.falkonry.ai/api/1.2/accounts/xxxxxxxxxxxxxxx/reports/yyyyyyyyyyyyyyyy/reportcontents'
TOKEN = '<token>'
HEADERS = {'Authorization': f'Bearer {TOKEN}', 'Content-Type': 'application/json'}
PAYLOAD = <Insert Json payload here>
response = requests.post(URL, headers=HEADERS, data=json.dumps(PAYLOAD))
print (response.json())
Example Response
{
"id": "1422685329511157760",
"type": "entities.reportcontent",
"tenant": "xxxxxxxxxxxxxxx",
"createTime": 1759265014770,
"updateTime": 1759265014770,
"createdBy": "596582102439518208",
"updatedBy": "596582102439518208",
"archived": false,
"name": "Timeline widget",
"report": "yyyyyyyyyyyyyyyy",
"contentType": "COVERSHEET",
"spec": {
"variables": [
{
"name": "reportcontent:signalGroups",
"type": "signalGroups",
"value": [
"1422685329523740672"
]
}
]
},
"links": []
}
Step 5: Organize Widgets on a Report Tab¶
Here's a preview on how to think about organizing the widgets on a report tab (page). UI allows adding upto 4 widgets into a 4x4 organizatoin with each widget getting equal space on the UI.
Request Parameters¶
reportcontent: Destination report IDi: Destination report IDtab id: Destination tab IDwidget id: Widget IDx: Horizontal position for the widget on the UIy: Vertical position for the widget on the UIw: Width of the widget on the UIh: Height of the widget on the UI
Request Payload¶
{
"grid": [{
"x" : "1", // Horizontal position
"y" : "0", // Vertical position
"w" : "1", // Width
"h" : "2", // Height
"reportcontent" : "aaaaaaaaaaaaaaaa",
"i" : "aaaaaaaaaaaaaaaa"
}]
}
Python¶
import requests
import json
URL = 'https://app3.falkonry.ai/api/1.2/accounts/xxxxxxxxxxxxxxx/reports/yyyyyyyyyyyyyyyy/organizers/zzzzzzzzzzzzzzz'
TOKEN = '<token>'
HEADERS = {'Authorization': f'Bearer {TOKEN}', 'Content-Type': 'application/json'}
PAYLOAD = <Insert Json payload here>
response = requests.post(URL, headers=HEADERS, data=json.dumps(PAYLOAD))
print (response.json())
Example Response
{
"id": "1422683106784206848",
"type": "entities.organizer",
"tenant": "xxxxxxxxxxxxxxx",
"createTime": 1759264484831,
"updateTime": 1759265016044,
"createdBy": "596582102439518208",
"updatedBy": "596582102439518208",
"archived": false,
"report": "yyyyyyyyyyyyyyyy",
"name": "Tab 3",
"grid": [
{
"x": 1,
"y": 0,
"w": 1,
"h": 2,
"reportcontent": "aaaaaaaaaaaaaaaa"
}
],
"links": []
}