Table of Contents

Vizpad-related APIs

Ramya Priya Updated by Ramya Priya

Here, you can find APIs for

  • Creating a Vizpad (POST)
  • Getting a list of all Vizpads (GET)
  • Renaming a Vizpad
  • Deleting a Vizpad (DELETE)
  • Cloning a Vizpad
  • Sharing a Vizpad with a user/user group
  • Disassociating a Vizpad from a user/user group
  • Getting the list of user/user groups a Vizpad is shared with
  • Generating embedding URL for a Vizpad

For accessing the following APIs, JSON Web Token (JWT) needs to be generated using login API.

Create a Vizpad

The API can be used to create a new Vizpad.

Request

URL
https://<TelliusUrl>/vizpad
CURL
curl -X POST 'https://<TelliusUrl>/vizpad' 
  -H 'Accept: application/json, text/plain, */*' \
  -H 'Authorization: Bearer token' \
  --data-binary '{"title":"name of the vizpad","thumbnail":"","sharingByLink":true,"sharedWith":[],"businessViewId":"businessView_id","tabs":[{"id":"id for the tab","name":"tab  name","placements":[],"filters":{"timeFilters":[],"valueFilters":{"operator":"and","negate":false,"id":null,"args":[]}}}]}'

Method
POST
Headers

By default, only superUsers can access this view.

Authorization: Bearer <AUTHENTICATION_TOKEN_FROM_LOGIN_API>
Content-Type: application/json, text/plain
Body
{
  "title":"name of the vizpad",
  "thumbnail":"",
  "sharingByLink":true,
  "sharedWith":[],
  "businessViewId":"businessView_id",
  "tabs":[{
    "id":"id for the tab",
    "name":"tab name",
    "placements":[],
    "filters":{
      "timeFilters":[],
      "valueFilters":{"operator":"and","negate":false,"id":null,"args":[]}
    }
  }]
}

Response

Success
Status Code: 200 OK
Body

A new Vizpad with the following properties will be created.

{
  "updatedAt":"2020-08-27T10:52:33.422707",
  "title":"name of the vizpad",
  "tabs":[{
    "placements":[],
    "name":"Name of the tab",
    "id":"tab id",
    "filters":{
      "valueFilters":{
        "operator":"and",
        "negate":false,
        "args":[]},
      "timeFilters":[]}}],
  "sharingByLink":true,
  "sharedWith":[],
  "owner":{
    "username":"username",
    "lastName":"last name",
    "id":"user-id",
    "firstName":"firstName"},
  "id":"id for the vizpad",
  "elements":[],
  "createdAt":"timestamp of when it was created",
  "businessViewId":"business view id"
}

Get a list of Vizpads

A Vizpad is made up of one or more tabs, and each tab consists of multiple viz. The API can be used to get the list of Vizpads. We need to send the username and password to receive the JWT token from the API response:

At the maximum, a Vizpad can have 10 tabs utmost, and each tab can have 25 viz.

Request

URL
https://<TelliusUrl>/vizpad?&includingShared=true&withSharings=true&limit=2&offset=0
CURL
curl -X POST 'https://<TelliusUrl>/vizpad' 
  -H 'Accept: application/json, text/plain, */*' \
  -H 'Authorization: Bearer token' \
  --data-binary '{"title":"name of the vizpad","thumbnail":"","sharingByLink":true,"sharedWith":[],"businessViewId":"businessView_id","tabs":[{"id":"id for the tab","name":"tab  name","placements":[],"filters":{"timeFilters":[],"valueFilters":{"operator":"and","negate":false,"id":null,"args":[]}}}]}'

Method
GET
Headers
Authorization: Bearer <AUTHENTICATION_TOKEN_FROM_LOGIN_API>
Content-Type: application/json, text/plain

Response

Success
Status Code: 200 OK
Body

The list of existing Vizpads will be retrieved.

{
   "vizPads":[
      {
         "vizPad":{
            "vizItemsCount":4,
            "updatedAt":"2020-05-29T06:05:06.553270",
            "title":"Untitled 202005291133",
            "timeRange":{

            },
            "thumbnail":"cebc379c-4528-4513-985d-96e3cba08f58",
            "tabs":[
               {
                  "placements":[
                     {
                        "vizTitle":"Untitled viz746",
                        "vizId":"9a2d6c29-4311-49c0-a7e1-4af6ce3faf87",
                        "sizeY":4,
                        "sizeX":4,
                        "row":0,
                        "col":0
                     },
                     {
                        "vizTitle":"Untitled viz64",
                        "vizId":"b02b5d54-b6b3-4e1d-bd72-e56ffa84d5db",
                        "sizeY":4,
                        "sizeX":4,
                        "row":0,
                        "col":4
                     },
                     {
                        "vizTitle":"Untitled viz839",
                        "vizId":"71ea78df-3431-4876-9b0b-7d103314cee4",
                        "sizeY":4,
                        "sizeX":4,
                        "row":0,
                        "col":8
                     },
                     {
                        "vizTitle":"Untitled viz659",
                        "vizId":"24d78e7f-2277-4095-9b79-1ad395d470e2",
                        "sizeY":4,
                        "sizeX":4,
                        "row":4,
                        "col":0
                     }
                  ],
                  "name":"Tab 1",
                  "id":"b5c82d04-b6c9-473d-89eb-5bd1311cce36",
                  "filters":{
                     "valueFilters":{
                        "operator":"and",
                        "negate":false,
                        "args":[

                        ]
                     },
                     "timeFilters":[

                     ]
                  }
               }
            ],
            "sharingByLink":true,
            "sharedWith":[

            ],
            "settings":{

            },
            "placement":[

            ],
            "owner":{
               "username":"superUser",
               "id":"2bcfb55d-d984-4e01-a5fb-bacd471bb5b4"
            },
            "id":"1d2fa8bf-e3f5-4eeb-8127-1c267b844cd5",
            "gradientPaletteId":"2cc9e757-9aa0-41e4-a46a-71fef9b590b0",
            "elements":[

            ],
            "createdAt":"2020-05-29T06:03:59.672464",
            "colorPaletteId":"7bd98706-4982-411c-aa1c-fd0f41f7a076",
            "businessViewId":"bv_7c08af86-e865-43c3-8f78-b92a624d2d7b"
         },
         "sharings":[

         ],
         "readOnly":false
      },
      {
         "vizPad":{
            "vizItemsCount":1,
            "updatedAt":"2020-05-29T06:00:00.646384",
            "title":"Untitled 202005291129",
            "timeRange":{

            },
            "thumbnail":"b490d590-7ade-40ac-bd33-8b545abf110f",
            "tabs":[
               {
                  "placements":[
                     {
                        "vizTitle":"Untitled viz995",
                        "vizId":"0da50d20-3c7b-4638-a4bc-60f4f292b70b",
                        "sizeY":4,
                        "sizeX":4,
                        "row":0,
                        "col":0
                     }
                  ],
                  "name":"Tab 1",
                  "id":"4e57fb43-a435-410f-ac99-fee1bd6c8412",
                  "filters":{
                     "valueFilters":{
                        "operator":"and",
                        "negate":false,
                        "args":[

                        ]
                     },
                     "timeFilters":[

                     ]
                  }
               }
            ],
            "sharingByLink":true,
            "sharedWith":[

            ],
            "settings":{

            },
            "placement":[

            ],
            "owner":{
               "username":"superUser",
               "id":"2bcfb55d-d984-4e01-a5fb-bacd471bb5b4"
            },
            "id":"597d3f28-5f8a-40d8-9404-c031e21bae8e",
            "gradientPaletteId":"2cc9e757-9aa0-41e4-a46a-71fef9b590b0",
            "elements":[

            ],
            "createdAt":"2020-05-29T05:59:38.302939",
            "colorPaletteId":"8858c2b5-b714-4ca4-9522-bc2d6c3c9911",
            "businessViewId":"bv_7c08af86-e865-43c3-8f78-b92a624d2d7b"
         },
         "sharings":[

         ],
         "readOnly":false
      }
   ],
   "totalCount":8
}

Rename a Vizpad

The API can be used to rename any existing Vizpad.

Request

URL

Replace vizpad_id with the ID of the Vizpad which needs to be renamed.

https://<telliusUrl>/vizpad/<vizpad_id>
CURL
curl 'https://<tellius-url>/vizpad/327e1130-75e4ef19d88b' \
  -X 'PUT' \
  -H 'Authorization: Bearer token' \
  --data-binary '{"title":"new vizpad name"}'

Method
PUT
Headers
Authorization: Bearer <AUTHENTICATION_TOKEN_FROM_LOGIN_API>
Content-Type: application/json, text/plain
Body
{
"title": "new vizpad name"
}

Response

Success
Status Code: 200 OK
Body

A new Vizpad with the following properties will be created.

{
"id": "327e1130-75e4ef19d88b",
"title": "new vizpad name"
}

Delete a Vizpad

The API can be used for deleting any existing Vizpad.

Request

URL

Replace vizpad_id with the ID of the Vizpad which needs to be deleted.

https://<telliusUrl>/vizpad/<vizpad_id>
CURL
 curl 'https://<TelliusUrl>/vizpad/<vizpad_id>' \
  -X 'DELETE' \
  -H 'Authorization: Bearer token' \
  --data-binary '{}' \

Method
DELETE
Headers
Authorization: Bearer <AUTHENTICATION_TOKEN_FROM_LOGIN_API>
Content-Type: application/json, text/plain

Response

Success
Status Code: 200 OK
Body

If the Vizpad is successfully deleted, the API will return a response with HTTP status code 200 and an empty response body.

Clone a Vizpad

The API can be used to create a duplicate of any existing Vizpad.

Request

URL

Replace vizpad_id with the ID of the Vizpad which needs to be cloned.

https://<telliusUrl>/vizpad/clone/<vizpad_id>
CURL
curl -X 'POST'\
'https://<telliusUrl>/vizpad/clone/<vizpad_id>' \
  -X 'POST' \
  -H 'Authorization: Bearer token' \
  --data-binary '{"title":"Name for the cloned vizpad"}'

Method
POST
Headers

By default, only superUsers can access this view.

Authorization: Bearer <AUTHENTICATION_TOKEN_FROM_LOGIN_API>
Content-Type: application/json, text/plain
Body
{
"title": "Name for the cloned vizpad"
}

Response

Success
Status Code: 200 OK
Body

The response body returns the details of the newly cloned vizpad, including its ID, title, tabs, owner, and timestamp of creation.

{
"updatedAt": "timestamp",
"title": "newly cloned vizpad name",
"tabs": [
{
"placements": [],
"name": "tab name",
"id": "tab id",
"filters": {
"valueFilters": {
"operator": "and",
"negate": false,
"args": []
},
"timeFilters": []
}
}
],
"sharingByLink": true,
"sharedWith": [],
"owner": {
"username": "username",
"lastName": "lastName",
"id": "user_id",
"firstName": "firstName"
},
"id": "new_vizpad_id",
"elements": [],
"createdAt": "timestamp",
"businessViewId": "businessView_id"
}

Share a Vizpad with a user or user group

The API can be used to share an existing Vizpad with any user/ user group.

Request

URL
https://<TelliusUrl>/share
CURL
curl -X 'POST'\
'https://<telliusUrl>/share' \
  -H 'Authorization: Bearer token' \
  --data-binary '{"sharedWithId":"user id of the  user to  share  with","objectId":"vizpad id" ,"objectKind":"vizPad","permission":"w[for write] or r  [for view]","sharedWithKind":"user or group"}'

Method
POST
Headers

By default, only superUsers can access this view.

Authorization: Bearer <AUTHENTICATION_TOKEN_FROM_LOGIN_API>
Content-Type: application/json, text/plain
Body
{
"sharedWithId": "user id of the user/group to share with",
"objectId": "vizpad id",
"objectKind": "vizPad",
"permission": "w [for write] or r [for view]",
"sharedWithKind": "user or group"
}

Response

Success
Status Code: 200 OK
Body

The response body returns the details of the sharing, including the sharing ID, the ID of the shared vizpad, the ID and name of the user or group it was shared with, and the level of permission granted.

{
"sharings": [
{
"updatedAt": "timestamp",
"sharedWithName": "user/group name",
"sharedWithKind": "user or group",
"sharedWithId": "shared with user/group id",
"permission": "w [for write] or r [for view]",
"owner": {
"username": "username",
"id": "user id of the owner"
},
"objectKind": "vizPad",
"objectId": "vizpad id",
"id": "object id",
"createdAt": "timestamp"
}
]
}

Dissociate a Vizpad from a user or user group

The API can be used to remove the sharing permissions of a Vizpad.

Request

URL
https://<TelliusUrl>/share/<share_id>
CURL
 curl 'https://<telliusUrl>/share/<share_id>' \
  -X 'DELETE' \
  -H 'Authorization: Bearer token' \
  --data-binary '{}'

Method
DELETE
Headers

By default, only superUsers can access this view.

Authorization: Bearer <AUTHENTICATION_TOKEN_FROM_LOGIN_API>
Content-Type: application/json

Response

Success
Status Code: 200 OK
Body

The response body will contain the details of the vizpad that was unshared, including its ID, the name of the user or user group it was shared with, the permission level (write or view), and the ID of the owner of the vizpad.

{
  "sharings":[{
  "updatedAt":"timestamp",
  "sharedWithName":"user/group name",
  "sharedWithKind":"user or group",
  "sharedWithId":"shared with user/group id",
  "permission":"w [for write] or r [for view]",
  "owner":{
    "username":"username",
    "id":"user id of the owner"},
  "objectKind":"vizPad",
  "objectId":"vizpad id",
  "id":"object id",
  "createdAt":"timestamp"
}]
}

List users or user groups a Vizpad is shared with

The API retrieves the list of users/user groups with whom a specific Vizpad has been shared.

Request

URL
https://<telliusUrl>/share?includingShared=true&objectKind=vizPad&objectId=<vizpad_id>
CURL
curl -X 'GET'
'https://<TelliusUrl>/share?includingShared=true&objectKind=vizPad&objectId=<vizpad_id>' \
  -H 'Connection: keep-alive' \
  -H 'Accept: application/json, text/plain, */*' \
  -H 'Authorization: Bearer token'
Method
GET
Headers

By default, only superUsers can access this view.

Authorization: Bearer <AUTHENTICATION_TOKEN_FROM_LOGIN_API>
Connection: keep-alive
Content-Type: application/json

Response

Success
Status Code: 200 OK
Body

The response body will contain a list of shared objects for the specified vizpad, including details such as the name of the user or user group it was shared with, the permission level (read or write), and the ID of the owner of the vizpad. If there are no shared objects for the specified vizpad, the response body will be an empty array.

{
  "sharings":[{
    "updatedAt":"timestamp",
    "sharedWithName":"userName",
    "sharedWithKind":"user or group",
    "sharedWithId":"share_with_id",
    "permission":"r or w [depending on read or write permission]",
    "owner":
    {
      "username":"username",
      "id":"user_id"
    },
    "objectKind":"vizPad",
    "objectId":"object_id",
    "id":"share_id",
    "createdAt":"timeStamp"}]
}

Get the list of Business Views

The API retrieves the list of Business Views.

Request

URL
https://<TELLIUS_URL>/businessViews?includeColumns=true&includingShared=true&withSharings=true
CURL
curl -X GET \
https://<TELLIUS_URL>//businessViews?includeColumns=true&includingShared=true&withSharings=true \
  -H 'authorization: Bearer <AUTHENTICATION_TOKEN_FROM_LOGIN_API>' \
  -H 'content-type: application/json' \
Method
GET
Headers

By default, only superUsers can access this view.

Authorization: Bearer <AUTHENTICATION_TOKEN_FROM_LOGIN_API>
Content-Type: application/json

Response

Success
Status Code: 200 OK
Body

The response body will retrieve the list of Business Views.

{
  "totalCount": <total number of business views>,
  "businessViews": [
    {
      "sharings": [],
      "readOnly": <read-only status of the business view>,
      ...
      "businessView": {
        "updatedAt": "<date and time of the last update of the business view>",
        "searchTokens": [],
        ...
      },
      ...
    },
    {
      "sharings": [],
      "readOnly": <read-only status of the business view>,
      ...
    },
    ...
  ]
}

Generate embedding URL for Vizpad

A new embedding URL has to be created for every tab in a Vizpad. Embedding URL for a Vizpad can be generated in View mode & Edit mode.

URL format for view mode

https://<TelliusUrl>/dashboard/<VizpadId>/<TabId>?access=read&datasetId=<BusinessViewId>&jwt=<JWT token received from the API>

URL format for edit mode

https://<TelliusUrl>/dashboard/<VizpadId>/<TabId>?access=edit&datasetId=<BusinessViewId>&jwt=<JWT token received from the API>

Did we help you?

Contact