Embed Data App API (CRUD)

APIs to create, update, delete, and list embed configurations associated with dashboards or metrics in data app.

API Endpoints

Cloud Databrain Endpoint

POST https://api.usedatabrain.com/api/v2/dataApp/embed/{method_path}

Self-hosted Databrain Endpoint

POST <SELF_HOSTED_URL>/api/v2/dataApp/embed/{method_path}

Name
Authorization*	String	Bearer API TOKEN

API Methods

POST /create

Create an embed configuration for a dashboard or a metric.

Request Body:

{
  "dashboardId": "string",
  "embedType": "dashboard" | "metric",
  "metricId": "string (required if embedType is 'metric')",
  "workspaceName": "string",
  "accessSettings": {
    "datamartName": "string",
    "isAllowAiPilot": true,
    "isAllowEmailReports": false,
    "isAllowManageMetrics": true,
    "isAllowMetricCreation": true,
    "isAllowMetricDeletion": true,
    "isAllowMetricLayoutChange": true,
    "isAllowMetricUpdate": true,
    "isAllowUnderlyingData": false,
    "metricCreationMode": "DRAG_DROP" | "CHAT",
    "tableList": [
      {
        "clientColumn": "string",
        "name": "string"
      }
    ] // database tenancy don't require table list
  }
}

Response

{
  "id": "string",
  "error": null
}

Error Response:

{
  "error": {
    "code": "string",
    "message": "string",
    "status": 400
  }
}

Possible Errors

Code	Message	HTTP Status
INVALID_WORKSPACE_NAME	Invalid workspace name	400
INVALID_DATA_APP_API_KEY	Missing or invalid data app	400
INVALID_DASHBOARD_ID	Dashboard not found	400
INVALID_METRIC_ID	Metric not found	400
INTERNAL_SERVER_ERROR	Unexpected failure	500
INVALID_DATAMART	Invalid datamart	400
DATAMART_TABLE_NOT_FOUND	Datamart table not found (If the datamart uses table-level tenancy but has no configured tables.)	400
INVALID_DATAMART (again, but with tenancy context)	Invalid datamart tenancy level (When the datamart’s tenancy level doesn't match the workspace’s expected tenancy.)	400

Update Embed

POST /update

Update the accessSettings for an existing embed.

Request Body

{
  "embedId": "string",
  "accessSettings": {
    "datamartName": "string",
    "isAllowAiPilot": true,
    "isAllowEmailReports": false,
    "isAllowManageMetrics": true,
    "isAllowMetricCreation": true,
    "isAllowMetricDeletion": true,
    "isAllowMetricLayoutChange": true,
    "isAllowMetricUpdate": true,
    "isAllowUnderlyingData": false,
    "metricCreationMode": "DRAG_DROP" | "CHAT",
    "tableList": [
      {
        "clientColumn": "string",
        "name": "string"
      }
    ]
  }
}

All accessSettings fields are optional; only provided fields will be updated.

Response

{
  "id": "string",
  "error": null
}

Possible Errors

Code	Message	HTTP Status
INVALID_DATA_APP_API_KEY	Missing or invalid data app	400
INVALID_EMBED_ID	Embed ID not found	400
INVALID_REQUEST_BODY	Access settings empty or malformed	400
INTERNAL_SERVER_ERROR	Unexpected failure	500

Delete Embed

POST /delete

Description:

Delete an existing embed using its embedId.

Request Body

{
  "embedId": "string"
}

Response

{
  "id": "string",
  "error": null
}

Possible Errors

Code	Message	HTTP Status
INVALID_DATA_APP_API_KEY	Missing or invalid data app	400
INVALID_REQUEST_BODY	Embed not found or invalid payload	400 or 500
INTERNAL_SERVER_ERROR	Unexpected failure	500

List Embeds

POST /list

Description:

Fetch a list of all embeds created by the authenticated data app.

Request Body

{
  "isPagination": "boolean (optional)",
  "pageNumber": "number (optional)" //10 items per page
}

Response

{
  "data": [
    {
      "embedId": "string",
      "externalDashboard": {
        "externalDashboardId": "string",
        "name":"string"
      },
      "externalMetric":{
        "externalMetricId":"string",
        "name":"string"
      },
      "embedType": "dashboard" | "metric",
      "embedDataAppAccessSetting": {
        "isAllowAiPilot": true,
        "isAllowEmailReports": false,
        "isAllowManageMetrics": true,
        "isAllowMetricCreation": true,
        "isAllowMetricDeletion": true,
        "isAllowMetricLayoutChange": true,
        "isAllowMetricUpdate": true,
        "isAllowUnderlyingData": false,
        "metricCreationMode": "DRAG_DROP" | "CHAT",
        "tableList": [
          {
            "clientColumn": "string",
            "name": "string"
          }
        ]
      }
    }
  ],
  "error": null
}

Possible Errors

Code	Message	HTTP Status
INVALID_DATA_APP_API_KEY	Missing or invalid data app	400
INTERNAL_SERVER_ERROR	Unexpected failure	500