Create widget | Sarvam API Docs

import requests
url = "https://apps.sarvam.ai/api/analytics/v1/org_id/workspace_id/boards/board_id/widgets"
payload = {
    "name": "Daily connected calls",
    "sql": "SELECT
  toDate(effective_datetime) AS day,
  countIf(v2v_connectivity_status = 'connected') AS connected,
  count() AS total
FROM EngagementFactsBoardsView
WHERE effective_datetime >= {{start_date}}
  [[AND app_id = {{agent_id}}]]
GROUP BY day
ORDER BY day",
    "viz_type": "line",
    "viz_config": {
        "x_axis": "day",
        "y_axis": ["connected", "total"]
    },
    "filters": [
        {
            "internal_name": "start_date",
            "display_label": "Start date",
            "filter_type": "date",
            "default_value": "2026-09-01"
        },
        {
            "internal_name": "agent_id",
            "display_label": "Agent",
            "filter_type": "string",
            "default_value": None
        }
    ],
    "tab_id": "6d1e84b3-9c07-4f52-b8ad-2e5f70c94a18"
}
headers = {
    "X-API-Key": "<your-api-key>",
    "Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())

{
  "id": "a4c9e0f7-31b8-4d6a-9e25-7f0b3c81d46e",
  "board_id": "0b7f2c9a-5e41-4d2a-9f3b-8c1d6e7a0b52",
  "name": "Daily connected calls",
  "sql": "SELECT\n  toDate(effective_datetime) AS day,\n  countIf(v2v_connectivity_status = 'connected') AS connected,\n  count() AS total\nFROM EngagementFactsBoardsView\nWHERE effective_datetime >= {{start_date}}\n  [[AND app_id = {{agent_id}}]]\nGROUP BY day\nORDER BY day",
  "viz_type": "line",
  "viz_config": {
    "x_axis": "day",
    "y_axis": [
      "connected",
      "total"
    ]
  },
  "created_by": {
    "type": "api_key",
    "id": "sk_live_a1b2c3"
  },
  "created_at": "2026-09-01T09:22:31Z",
  "updated_by": {
    "type": "api_key",
    "id": "sk_live_a1b2c3"
  },
  "updated_at": "2026-09-10T14:03:55Z"
}

Validates the SQL, registers the filter tokens it declares, and places the widget on tab_id or the board’s first tab.

Path parameters

org_idstringRequired

Organization ID

workspace_idstringRequired

Workspace ID

board_idstringRequiredformat: "uuid"

Request

This endpoint expects an object.

namestringRequired1-60 characters

Widget display name

sqlstringRequired>=1 character

Read-only SELECT against the workspace’s analytics views. Filter tokens use {{name}} for a required value and [[AND col = {{name}}]] for a clause that is dropped when the value is absent. Tenant scoping is enforced server-side.

viz_typeenumOptionalDefaults to table

How the result is rendered

viz_configobjectOptional

Renderer options for viz_type

filterslist of objectsOptional

Declarations for the filter tokens used in sql

tab_idstring or nullOptionalformat: "uuid"

Target tab. Defaults to the board's first tab when absent.

Response

Successful Response

idstringformat: "uuid"

Widget identifier

board_idstringformat: "uuid"

Board this widget belongs to

namestring

Widget display name

sqlstring

The widget's stored SQL, filter tokens unexpanded

viz_typestring

How the result is rendered

viz_configobject

Renderer options for viz_type

created_byobject

Actor that created the widget

created_atdatetime

Creation time, UTC, RFC 3339

updated_byobject

Actor that last changed the widget

updated_atdatetime

Last change time, UTC, RFC 3339

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

422

Unprocessable Entity Error

429

Too Many Requests Error

500

Internal Server Error

Path parameters

Headers

Request

Response

Errors