AI Endpoints

EU:  https://api.eu.embeddable.com
US:  https://api.us.embeddable.com

Authorization: Bearer <security-token-jwt>

// Always generate tokens server-side — never from client code
const response = await fetch('https://api.eu.embeddable.com/api/v1/security-token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${apiKey}`
  },
  body: JSON.stringify({
    embeddableId: '<dashboard-id>',
    savedVersion: 'production',
    user: 'user@example.com',
    // ... other fields
  })
});
const { token } = await response.json();
// Pass `token` to your AI agent for all /ai/v1/* calls

End User
  │  "Add a KPI chart showing sales performance this quarter in terms of dollars"
  ▼
Customer's AI Agent
  │  GET  /ai/v1/embeddable/metadata          → available chart types & datasets
  │  GET  /ai/v1/models                       → data model schema
  │  POST /ai/v1/query                        → run and verify a data query
  │  GET  /ai/v1/custom-canvas/request-state  → current canvas contents
  │  POST /ai/v1/custom-canvas/create         → place chart on canvas
  ▼
Embeddable API  (authenticated via Security Token)
  │  Applies row-level security
  │  Writes chart to end user's Custom Canvas
  ▼
End User sees the chart on their canvas

End User
  │  "Show me sales performance this quarter"
  ▼
Customer's AI Agent
  │  GET  /ai/v1/embeddable/metadata          → available chart types & datasets
  │  GET  /ai/v1/models                       → data model schema
  │  POST /ai/v1/query                        → run and verify a data query
  ▼
Embeddable API  (authenticated via Security Token)
  │  Applies row-level security
  │  Returns data to the agent
  ▼
End User sees the data in the agent's response (table, summary, etc.)

{
  "widgets": [
    {
      "id": "<uuid>",
      "name": "string",
      "inputConfiguration": { "<inputName>": "<value>" }
    }
  ],
  "selfServeWidgets": [ { "..." } ],
  "templateWidgets": [
    {
      "id": "<uuid>",
      "name": "string",
      "inputConfiguration": { "..." }
    }
  ],
  "starterCanvasWidgets": [
    {
      "id": "<uuid>",
      "templateId": "<uuid>",
      "inputConfiguration": { "..." },
      "filters": {},
      "limit": {},
      "order": {},
      "w": 4,
      "h": 3
    }
  ],
  "variables": [
    {
      "id": "<uuid>",
      "name": "string",
      "type": "string",
      "defaultValue": "string",
      "array": false
    }
  ],
  "variableListeners": { "<variableId>": ["<dependentVariableId>"] },
  "dashboardParams": { "..." },
  "datasets": [
    {
      "id": "<uuid>",
      "name": "string",
      "model": "string",
      "availableInCustomCanvas": true
    }
  ],
  "bundleHash": "string"
}

[
  {
    "name": "orders",
    "title": "Orders",
    "connectedComponent": 1,
    "dimensions": [
      {
        "name": "orders.status",
        "title": "Status",
        "nativeType": "string",
        "description": "Order status",
        "meta": null,
        "__type__": "dimension"
      }
    ],
    "measures": [
      {
        "name": "orders.count",
        "title": "Count",
        "nativeType": "number",
        "description": null,
        "meta": null,
        "__type__": "measure"
      }
    ]
  }
]

{
  "datasetId": "<uuid>",
  "dimensions": ["orders.status", "orders.createdAt"],
  "measures": ["orders.count", "orders.revenue"],
  "filters": [
    { "member": "orders.status", "operator": "equals", "values": ["completed"] }
  ],
  "timeDimensions": [
    {
      "dimension": "orders.createdAt",
      "dateRange": ["2024-01-01", "2024-12-31"],
      "granularity": "month"
    }
  ],
  "order": [["orders.createdAt", "asc"]],
  "limit": 100,
  "offset": 0,
  "timezone": "America/New_York",
  "countRows": false
}

{
  "cubeRequestId": "<uuid>",
  "externalRequestId": "<uuid>",
  "requestSequenceNumber": 1,
  "data": [
    { "orders.status": "completed", "orders.count": 142 }
  ],
  "total": 142,
  "error": null,
  "preAggregationTriggered": false
}

{
  "components": [
    {
      "id": "<uuid>",
      "templateId": "<uuid>",
      "key": "string",
      "inputConfiguration": { "<inputName>": "<value>" },
      "subInputConfiguration": {
        "<parentInputName>": {
          "<parentValue>": { "<subInputName>": "<value>" }
        }
      },
      "filters": {
        "<datasetName>": [
          {
            "member": "model.field",
            "operator": "equals",
            "value": "x",
            "valueType": "string",
            "nativeDataType": "string"
          }
        ]
      },
      "limit": { "<datasetName>": 100 },
      "order": { "<datasetName>": ["model.field asc"] },
      "w": 4,
      "h": 3,
      "heightResolution": null,
      "widthResolution": null
    }
  ],
  "version": 5
}

{
  "id": "<uuid>",
  "templateId": "<uuid>",
  "requestId": "<uuid>",
  "inputConfiguration": {
    "datasetId": "<uuid>",
    "measure": {
      "name": "orders.count",
      "title": "Count",
      "nativeType": "number",
      "description": null,
      "meta": null,
      "__type__": "measure"
    }
  },
  "filters": {},
  "limit": {},
  "order": {},
  "w": 4,
  "h": 3
}

{
  "id": "<uuid>",
  "requestId": "<uuid>",
  "inputConfiguration": {
    "datasetId": "<uuid>",
    "measure": {
      "name": "orders.revenue",
      "title": "Revenue",
      "nativeType": "number",
      "description": null,
      "meta": null,
      "__type__": "measure"
    }
  },
  "filters": {},
  "limit": {},
  "order": {}
}

{
  "id": "<uuid>",
  "requestId": "<uuid>"
}

{
  "updates": {
    "<widget-uuid>": 0,
    "<widget-uuid-2>": 1
  },
  "requestId": "<uuid>"
}

{
  "id": "<uuid>",
  "requestId": "<uuid>",
  "w": 8,
  "h": 4
}

{
  "errorType": "PROBLEM_LOADING_DATA",
  "message": "...",
  "retryMessage": "Try again later"
}

Customer's AI Agent
  │  Receives tokens: [token_A (embeddable A), token_B (embeddable B)]
  │
  ├── GET /ai/v1/embeddable/metadata (token_A) → chart types for embeddable A
  ├── GET /ai/v1/embeddable/metadata (token_B) → chart types for embeddable B
  │
  │  AI identifies which embeddable is relevant for the operation
  │
  ├── POST /ai/v1/custom-canvas/create (token_A) → chart on embeddable A canvas
  └── POST /ai/v1/custom-canvas/create (token_B) → chart on embeddable B canvas

pip install fastmcp httpx

python mcp_ai_agent.py

import os
import json
import httpx
from mcp.server.fastmcp import FastMCP
 
mcp = FastMCP("embeddable-ai-agent")
 
BASE_URL = os.getenv("EMBEDDABLE_BASE_URL", "")
TOKEN = os.getenv("EMBEDDABLE_TOKEN", "")
 
 
def headers():
    if not TOKEN:
        raise ValueError("EMBEDDABLE_TOKEN is not set. Please set it via environment variable or ask the user.")
    return {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}
 
 
@mcp.tool()
def get_models() -> str:
    """Returns available Cube data models with their dimensions and measures."""
    with httpx.Client() as client:
        response = client.get(f"{BASE_URL}/ai/v1/models", headers=headers())
        response.raise_for_status()
        return json.dumps(response.json(), indent=2)
 
 
@mcp.tool()
def execute_query(
    dataset_id: str,
    dimensions: list[str] | None = None,
    measures: list[str] | None = None,
    filters: list[dict] | None = None,
    time_dimensions: list[dict] | None = None,
    order: list[list[str]] | None = None,
    limit: int | None = None,
    offset: int | None = None,
    timezone: str | None = None,
    count_rows: bool = False,
) -> str:
    """
    Execute a data query against the embeddable's model.
 
    dataset_id: UUID of the dataset to query against.
 
    filters format: [{"member": "model.field", "operator": "equals", "values": ["value"]}]
    Operators: equals, notEquals, contains, notContains, startsWith, endsWith, gt, gte, lt, lte, set, notSet, inDateRange, notInDateRange, beforeDate, afterDate, measureFilter
 
    time_dimensions format: [{"dimension": "model.date", "dateRange": ["YYYY-MM-DD", "YYYY-MM-DD"], "granularity": "day"}]
    Granularity options: second, minute, hour, day, week, month, quarter, year
 
    order format: [["model.field", "asc"]]
    """
    body = {k: v for k, v in {
        "datasetId": dataset_id,
        "dimensions": dimensions,
        "measures": measures,
        "filters": filters,
        "timeDimensions": time_dimensions,
        "order": order,
        "limit": limit,
        "offset": offset,
        "timezone": timezone,
        "countRows": count_rows,
    }.items() if v is not None}
 
    with httpx.Client() as client:
        response = client.post(f"{BASE_URL}/ai/v1/query", headers=headers(), json=body)
        response.raise_for_status()
        return json.dumps(response.json(), indent=2)
 
 
@mcp.tool()
def get_datasets() -> str:
    """Returns available datasets with their id, name, model, and availableInCustomCanvas flag. Use this to resolve a datasetId before calling execute_query."""
    with httpx.Client() as client:
        response = client.get(f"{BASE_URL}/ai/v1/embeddable/metadata", headers=headers())
        response.raise_for_status()
        return json.dumps(response.json().get("datasets", []), indent=2)
 
 
@mcp.tool()
def get_embeddable_metadata() -> str:
    """
    Returns full embeddable config including:
    - widgets: configured chart/table widgets with their inputConfiguration
    - selfServeWidgets: self-serve widgets available for the canvas
    - templateWidgets: reusable template chart definitions
    - starterCanvasWidgets: pre-built starter layout widgets (each has id, templateId, inputConfiguration, filters, limit, order, w, h)
    - variables: dashboard variables (id, name, type, defaultValue, array)
    - variableListeners: variable dependency graph
    - dashboardParams: global dashboard parameters
    - datasets: available datasets (id, name, model, availableInCustomCanvas)
    - bundleHash: current bundle version hash
    """
    with httpx.Client() as client:
        response = client.get(f"{BASE_URL}/ai/v1/embeddable/metadata", headers=headers())
        response.raise_for_status()
        return json.dumps(response.json(), indent=2)
 
 
@mcp.tool()
def get_canvas_state() -> str:
    """
    Returns the current custom canvas state including:
    - components: list of widgets on the canvas, each with:
        - id (UUID), templateId (UUID), key (string)
        - inputConfiguration: Map<string, any> of input values
        - subInputConfiguration: nested per-value input overrides
        - filters: Map<datasetName, list of filters> where each filter has member, operator, value, valueType, nativeDataType
        - limit: Map<datasetName, int>
        - order: Map<datasetName, list of strings>
        - w (1-16), h (1-12), heightResolution (1-4), widthResolution (1-2)
    - version: canvas version number
    """
    with httpx.Client() as client:
        response = client.get(f"{BASE_URL}/ai/v1/custom-canvas/request-state", headers=headers())
        response.raise_for_status()
        return json.dumps(response.json(), indent=2)
 
 
@mcp.tool()
def create_canvas_widget(
    id: str,
    template_id: str,
    request_id: str,
    input_configuration: dict,
    sub_input_configuration: dict | None = None,
    filters: dict | None = None,
    limit: dict | None = None,
    order: dict | None = None,
    w: int = 1,
    h: int = 1,
    height_resolution: int | None = None,
    width_resolution: int | None = None,
) -> str:
    """
    Add a new widget to the custom canvas.
 
    id: UUID for the new widget instance.
    template_id: UUID of the template chart to instantiate (from get_embeddable_metadata templateWidgets).
    request_id: Unique UUID for this request (for idempotency).
    input_configuration: Map of input name -> value. Key names come from the template definition (e.g. "measure" for KPI/Donut, "measures" for Bar/Line). Member values must be full member objects: {"name": "model.field", "title": "...", "nativeType": "...", "__type__": "measure"}.
    sub_input_configuration: Optional nested per-value input overrides. Key is parent input name (e.g. "columns"),
        value is Map<parentValue, Map<inputName, any>>.
    filters: Optional Map<datasetName, list of filters>. Each filter: {"member": "model.field", "operator": "equals", "value": "x", "valueType": "...", "nativeDataType": "..."}.
    limit: Optional Map<datasetName, int> row limits per dataset.
    order: Optional Map<datasetName, list of strings> sort order per dataset.
    w: Width in grid columns (1-16, default 1).
    h: Height in grid rows (1-12, default 1).
    height_resolution: Optional height resolution multiplier (1-4).
    width_resolution: Optional width resolution multiplier (1-2).
    """
    body = {k: v for k, v in {
        "id": id,
        "templateId": template_id,
        "requestId": request_id,
        "inputConfiguration": input_configuration,
        "subInputConfiguration": sub_input_configuration,
        "filters": filters,
        "limit": limit,
        "order": order,
        "w": w,
        "h": h,
        "heightResolution": height_resolution,
        "widthResolution": width_resolution,
    }.items() if v is not None}
    with httpx.Client() as client:
        response = client.post(f"{BASE_URL}/ai/v1/custom-canvas/create", headers=headers(), json=body)
        response.raise_for_status()
        return json.dumps(response.json(), indent=2)
 
 
@mcp.tool()
def update_canvas_widget(
    id: str,
    request_id: str,
    input_configuration: dict,
    sub_input_configuration: dict | None = None,
    filters: dict | None = None,
    limit: dict | None = None,
    order: dict | None = None,
) -> str:
    """
    Update an existing widget on the custom canvas.
 
    id: UUID of the widget to update (from get_canvas_state components).
    request_id: Unique UUID for this request (for idempotency).
    input_configuration: Full replacement Map of input name -> value.
    sub_input_configuration: Optional nested per-value input overrides (replaces existing).
    filters: Optional Map<datasetName, list of filters> (replaces existing).
    limit: Optional Map<datasetName, int> (replaces existing).
    order: Optional Map<datasetName, list of strings> (replaces existing).
    """
    body = {k: v for k, v in {
        "id": id,
        "requestId": request_id,
        "inputConfiguration": input_configuration,
        "subInputConfiguration": sub_input_configuration,
        "filters": filters,
        "limit": limit,
        "order": order,
    }.items() if v is not None}
    with httpx.Client() as client:
        response = client.put(f"{BASE_URL}/ai/v1/custom-canvas/update", headers=headers(), json=body)
        response.raise_for_status()
        return json.dumps(response.json(), indent=2)
 
 
@mcp.tool()
def delete_canvas_widget(id: str, request_id: str) -> str:
    """
    Remove a widget from the custom canvas.
 
    id: UUID of the widget to delete (from get_canvas_state components).
    request_id: Unique UUID for this request (for idempotency).
    """
    body = {"id": id, "requestId": request_id}
    with httpx.Client() as client:
        response = client.request("DELETE", f"{BASE_URL}/ai/v1/custom-canvas/delete", headers=headers(), json=body)
        response.raise_for_status()
        return "Deleted successfully"
 
 
@mcp.tool()
def reorder_canvas_widgets(updates: dict, request_id: str) -> str:
    """
    Reorder widgets on the custom canvas.
 
    updates: Map of widget UUID -> new zero-based index position (e.g. {"<uuid>": 0, "<uuid2>": 1}).
    request_id: Unique UUID for this request (for idempotency).
    """
    body = {"updates": updates, "requestId": request_id}
    with httpx.Client() as client:
        response = client.post(f"{BASE_URL}/ai/v1/custom-canvas/reorder", headers=headers(), json=body)
        response.raise_for_status()
        return "Reordered successfully"
 
 
@mcp.tool()
def resize_canvas_widget(
    id: str,
    request_id: str,
    w: int,
    h: int,
    height_resolution: int | None = None,
    width_resolution: int | None = None,
) -> str:
    """
    Resize a widget on the custom canvas.
 
    id: UUID of the widget to resize (from get_canvas_state components).
    request_id: Unique UUID for this request (for idempotency).
    w: New width in grid columns (1-16).
    h: New height in grid rows (1-12).
    height_resolution: Optional height resolution multiplier (1-4).
    width_resolution: Optional width resolution multiplier (1-2).
    """
    body = {k: v for k, v in {
        "id": id,
        "requestId": request_id,
        "w": w,
        "h": h,
        "heightResolution": height_resolution,
        "widthResolution": width_resolution,
    }.items() if v is not None}
    with httpx.Client() as client:
        response = client.post(f"{BASE_URL}/ai/v1/custom-canvas/resize", headers=headers(), json=body)
        response.raise_for_status()
        return "Resized successfully"
 
 
if __name__ == "__main__":
    mcp.run()