Fully x402 Enabled → Agents Pay AutomaticallyLearn how
    v1 · stable

    TableCharts Agent API

    One endpoint. Send tabular data, get a live dashboard URL back in one round-trip.

    A2A-only service. No human UI for end users — this is a backend service consumed by other AI agents.

    NEW
    x402 protocol

    Let your agents pay automatically

    When quota runs out, we return 402 Payment Required with a buy_url. Your agent pays and retries — no human loop.

    Read the x402 guide →
    python — 402 detect + auto-retry
    import os, time, requests
    
    ENDPOINT = "https://xsbzchiryhqatvrzgyxm.supabase.co/functions/v1/generate-dashboard"
    AUTH = {"Authorization": f"Bearer {os.environ['TC_API_KEY']}"}
    
    def generate_with_x402(payload, wallet_pay_fn, tries=3):
        """Call TableCharts; if 402, pay via buy_url and retry."""
        for attempt in range(tries):
            r = requests.post(ENDPOINT, headers=AUTH, json=payload, timeout=30)
            if r.status_code == 402:
                invoice = r.json()          # {amount, currency, buy_url, nonce, ...}
                settlement = wallet_pay_fn(invoice)   # agent settles (Stripe or USDC)
                AUTH["X-PAYMENT"] = settlement
                continue
            r.raise_for_status()
            return r.json()                 # {dashboard_url, embed_iframe, ...}
        raise RuntimeError("x402 retry limit exceeded")
    GROK
    Custom Connector

    Connect TableCharts inside Grok

    1. Go to grok.com/connectors → New Connector → Custom
    2. Paste this server URL:
    Grok MCP server URL
    https://xsbzchiryhqatvrzgyxm.supabase.co/functions/v1/mcp-grok
    1. Start a new chat and turn Table Charts on.
    2. Ask: "Use Table Charts create_chart on this table…"

    Overview

    TableCharts is a Chart Generation Agent. Other AI agents send raw tabular data via REST, Google's A2A protocol, or email, and receive a live-updating dashboard URL (and iframe snippet) in one round-trip. The dashboard re-fetches its source data automatically — your agent does not need to repost.

    Quickstart

    Subscribe to any weekly plan (from $29/week), grab a key from /dashboard/api-keys, then paste this into your terminal.

    curl
    curl -X POST https://xsbzchiryhqatvrzgyxm.supabase.co/functions/v1/generate-dashboard \
      -H "Authorization: Bearer tc_live_<your_key>" \
      -H "Content-Type: application/json" \
      -d '{"data":[{"month":"Jan","revenue":42000},{"month":"Feb","revenue":48000},{"month":"Mar","revenue":56000}],"title":"Q1 Revenue"}'

    Health check: curl https://xsbzchiryhqatvrzgyxm.supabase.co/functions/v1/health

    Base URL

    canonical function URL
    https://xsbzchiryhqatvrzgyxm.supabase.co/functions/v1/generate-dashboard

    One stable URL. Health check at https://xsbzchiryhqatvrzgyxm.supabase.co/functions/v1/health.

    Authentication

    API key required. All /generate-dashboard calls must include Authorization: Bearer tc_live_…. Free tier includes 10 dashboards with no credit card. Paid plans start at $29/month (100 charts) or $0.59/chart via x402.

    Each successful call consumes one quota slot or one prepaid top-up credit. When all are zero the endpoint returns 402 with {code:"quota_exhausted"} and a buy_url pointing to /pricing#topups. Create a key at /dashboard/api-keys (sign in first). See pricing for plans and top-ups.

    authenticated request
    curl -X POST https://xsbzchiryhqatvrzgyxm.supabase.co/functions/v1/generate-dashboard \
      -H "Authorization: Bearer tc_live_..." \
      -H "Content-Type: application/json" \
      -d '{"data": [...]}'

    Get an API key at /api-keys (sign in first).

    Use it as Authorization: Bearer tc_live_…

    The Grok MCP endpoint uses this same key, stored server-side as the GROK_MCP_KEY secret — no key in the URL.

    POST /generate-dashboard

    The single endpoint. Accepts one of data, csv, or source_url.

    Request fields

    FieldTypeRequiredNotes
    dataarray<object>one ofFlat key/value rows.
    csvstringone ofRaw CSV with header row.
    source_urlstringone ofPublic Notion DB, Google Sheet, or CSV URL.
    titlestringnoDashboard title.
    descriptionstringnoShort caption shown on the embed.
    chart_typestringnoOverride auto-selection. See below.

    Response fields

    FieldTypeNotes
    okbooleantrue on 200.
    dashboard_urlstringPublic embed URL.
    embed_urlstringAlias of dashboard_url.
    embed_iframestringReady-to-paste iframe snippet.
    embed_idstringStable id for later reference.
    chart_typestringThe selected chart type.
    rowsnumberRow count after cleaning.

    Input modes

    Inline JSON

    request
    {
      "data": [
        { "month": "Jan", "revenue": 42000 },
        { "month": "Feb", "revenue": 48000 }
      ],
      "title": "Q1 Revenue"
    }

    CSV string

    request
    {
      "csv": "name,score\nAlice,92\nBob,87\nCarol,75",
      "title": "Team Scores",
      "chart_type": "bar"
    }

    Source URL

    Supported sources: public Notion databases, public Google Sheets, public CSV URLs, and Salesforce SOQL (with a connected token).

    request
    {
      "source_url": "https://www.notion.so/<workspace>/<database-id>",
      "title": "Roadmap Status"
    }

    Chart types

    Auto-selection picks one for you. To override, set chart_type to any of:

    bar
    line
    area
    pie
    doughnut
    radar
    scatter
    stacked-bar
    horizontal-bar

    Code examples

    Python (requests)
    import os
    import requests
    
    api_key = os.environ["TABLECHARTS_KEY"]
    
    r = requests.post(
        "https://xsbzchiryhqatvrzgyxm.supabase.co/functions/v1/generate-dashboard",
        headers={"Authorization": f"Bearer {api_key}"},
        json={
            "data": [
                {"month": "Jan", "revenue": 42000},
                {"month": "Feb", "revenue": 48000},
                {"month": "Mar", "revenue": 56000},
            ],
            "title": "Q1 Revenue",
        },
        timeout=30,
    )
    print(r.json()["dashboard_url"])
    TypeScript (fetch)
    const res = await fetch("https://xsbzchiryhqatvrzgyxm.supabase.co/functions/v1/generate-dashboard", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "Authorization": `Bearer ${process.env.TABLECHARTS_KEY}`,
      },
      body: JSON.stringify({
        data: rows,
        title: "Q3 Pipeline",
        chart_type: "bar",
      }),
    });
    const { dashboard_url, embed_iframe } = await res.json();
    LangChain — @tool wrapper
    import os
    from langchain_core.tools import tool
    import requests
    
    @tool
    def generate_dashboard(data: list[dict], title: str = "Dashboard") -> str:
        """Send tabular data to TableCharts; returns a live dashboard URL."""
        r = requests.post(
            "https://xsbzchiryhqatvrzgyxm.supabase.co/functions/v1/generate-dashboard",
            headers={"Authorization": f"Bearer {os.environ['TABLECHARTS_KEY']}"},
            json={"data": data, "title": title},
            timeout=30,
        )
        r.raise_for_status()
        return r.json()["dashboard_url"]
    CrewAI — @tool wrapper
    import os
    from crewai_tools import tool
    import requests
    
    @tool("TableCharts Dashboard")
    def tablecharts(data: list[dict], title: str = "Dashboard") -> str:
        """Turn a list of row dicts into a live dashboard URL."""
        r = requests.post(
            "https://xsbzchiryhqatvrzgyxm.supabase.co/functions/v1/generate-dashboard",
            headers={"Authorization": f"Bearer {os.environ['TABLECHARTS_KEY']}"},
            json={"data": data, "title": title},
            timeout=30,
        )
        return r.json()["dashboard_url"]
    OpenAI function-calling schema
    {
      "type": "function",
      "function": {
        "name": "generate_dashboard",
        "description": "Generate a live, embeddable dashboard from tabular data.",
        "parameters": {
          "type": "object",
          "properties": {
            "data":       { "type": "array",  "items": { "type": "object" } },
            "csv":        { "type": "string" },
            "source_url": { "type": "string" },
            "title":      { "type": "string" },
            "chart_type": { "type": "string", "enum": ["bar","line","area","pie","doughnut","radar"] }
          }
        }
      }
    }

    Ready-to-use examples

    Copy-paste

    Full working tool nodes for the two most common agent frameworks. Each snippet uses realistic revenue data, reads the X-Chart-Billing response header for observability, and includes a hook for the x402 retry flow.

    Billing behavior: Agents automatically use prepaid credits (or an active subscription) first, then fall back to $0.59 per chart via x402 when the quota is exhausted. See the x402 guide for the full pay-then-retry pattern.

    LangGraph — tool node with state
    """LangGraph tool node — TableCharts dashboard generator.
    
    Agents automatically use prepaid credits first, then fall back to
    $0.59 per chart via x402 when the quota is exhausted.
    """
    import os
    import requests
    from typing import TypedDict, Annotated
    from langgraph.graph import StateGraph, END
    from langgraph.prebuilt import ToolNode
    from langchain_core.tools import tool
    
    API_URL = "https://xsbzchiryhqatvrzgyxm.supabase.co/functions/v1/generate-dashboard"
    
    
    class AgentState(TypedDict):
        rows: list[dict]
        title: str
        dashboard_url: str | None
        billing_source: str | None  # subscription | prepaid | trial | x402
    
    
    @tool
    def tablecharts_dashboard(rows: list[dict], title: str = "Dashboard") -> dict:
        """Turn a list of row dicts into a live TableCharts dashboard URL."""
        r = requests.post(
            API_URL,
            headers={"Authorization": f"Bearer {os.environ['TABLECHARTS_KEY']}"},
            json={"data": rows, "title": title},
            timeout=30,
        )
    
        # On 402, hand off to the x402 pay-then-retry helper (see /x402 docs).
        if r.status_code == 402:
            raise RuntimeError("quota_exhausted — run x402 pay+retry loop")
    
        r.raise_for_status()
        body = r.json()
        return {
            "dashboard_url": body["dashboard_url"],
            # Observability: which credit bucket paid for this chart.
            "billing_source": r.headers.get("X-Chart-Billing", "unknown"),
        }
    
    
    def chart_node(state: AgentState) -> AgentState:
        result = tablecharts_dashboard.invoke(
            {"rows": state["rows"], "title": state["title"]}
        )
        return {**state, **result}
    
    
    graph = StateGraph(AgentState)
    graph.add_node("chart", chart_node)
    graph.set_entry_point("chart")
    graph.add_edge("chart", END)
    app = graph.compile()
    
    # ---- Example run --------------------------------------------------------
    sales = [
        {"month": "Jan", "revenue": 42000},
        {"month": "Feb", "revenue": 48000},
        {"month": "Mar", "revenue": 56000},
        {"month": "Apr", "revenue": 61500},
    ]
    final = app.invoke({"rows": sales, "title": "Q1 Revenue", "dashboard_url": None, "billing_source": None})
    print(final["dashboard_url"], "· billed via:", final["billing_source"])
    CrewAI — custom BaseTool
    """CrewAI custom Tool — TableCharts dashboard generator.
    
    Agents automatically use prepaid credits first, then fall back to
    $0.59 per chart via x402 when the quota is exhausted.
    """
    import os
    import requests
    from typing import Type
    from pydantic import BaseModel, Field
    from crewai import Agent, Task, Crew
    from crewai.tools import BaseTool
    
    API_URL = "https://xsbzchiryhqatvrzgyxm.supabase.co/functions/v1/generate-dashboard"
    
    
    class TableChartsInput(BaseModel):
        rows: list[dict] = Field(..., description="Row objects with consistent keys.")
        title: str = Field("Dashboard", description="Human-friendly dashboard title.")
    
    
    class TableChartsTool(BaseTool):
        name: str = "tablecharts_dashboard"
        description: str = (
            "Generate a live, embeddable dashboard URL from tabular sales/revenue "
            "data. Returns the dashboard URL and the billing source header."
        )
        args_schema: Type[BaseModel] = TableChartsInput
    
        def _run(self, rows: list[dict], title: str = "Dashboard") -> str:
            r = requests.post(
                API_URL,
                headers={"Authorization": f"Bearer {os.environ['TABLECHARTS_KEY']}"},
                json={"data": rows, "title": title},
                timeout=30,
            )
    
            # On 402, run the x402 pay-then-retry helper (see /x402 docs).
            if r.status_code == 402:
                return "ERROR: quota_exhausted — run x402 pay+retry loop"
    
            r.raise_for_status()
            body = r.json()
            billing = r.headers.get("X-Chart-Billing", "unknown")
            return f"{body['dashboard_url']} (billed via: {billing})"
    
    
    # ---- Example crew -------------------------------------------------------
    analyst = Agent(
        role="Revenue Analyst",
        goal="Visualize quarterly sales for the exec review.",
        backstory="A pragmatic FP&A analyst who prefers pictures over pivot tables.",
        tools=[TableChartsTool()],
    )
    
    sales = [
        {"quarter": "Q1", "revenue": 156000},
        {"quarter": "Q2", "revenue": 189000},
        {"quarter": "Q3", "revenue": 214500},
        {"quarter": "Q4", "revenue": 267000},
    ]
    
    task = Task(
        description=f"Chart this revenue data and return the dashboard URL: {sales}",
        expected_output="A TableCharts dashboard URL.",
        agent=analyst,
    )
    
    crew = Crew(agents=[analyst], tasks=[task])
    print(crew.kickoff())

    A2A protocol

    Agent Card is published at /.well-known/agent-card.json. Orchestrators following Google's A2A spec can discover skills, input modes, and pricing automatically.

    Primary skill id: generate_dashboard.

    A2A tasks/send envelope
    {
      "jsonrpc": "2.0",
      "method": "tasks/send",
      "params": {
        "id": "task-001",
        "skill": "generate_dashboard",
        "message": {
          "role": "user",
          "parts": [{
            "kind": "data",
            "data": {
              "data": [{ "month": "Jan", "revenue": 42000 }],
              "title": "Q1 Revenue"
            }
          }]
        }
      }
    }

    Email trigger

    Send a CSV/JSON attachment or a Notion/Sheets link to charts@tablecharts.co. The reply contains the dashboard URL within ~10s. Sender must be registered.

    Errors

    StatusMeaning
    400Bad input — missing or invalid data/csv/source_url.
    401Invalid Bearer token.
    402Quota exhausted. Response includes code:"quota_exhausted" and buy_url.
    429Rate limit exceeded.
    500Internal — safe to retry once with backoff.
    error shape
    { "error": "Provide one of: data (array), csv (string), or source_url (string)" }

    Rate limits

    TierLimit
    Authenticated (key)1,000 / hour / key (subject to monthly quota)
    Starter Monthly100 dashboards / month, $0.49 overage
    Pro Monthly400 dashboards / month, $0.39 overage
    x402 (agents)$0.59 USDC per chart · no signup
    Prepaid bundles15 / 60 / 200 / 600 credits — never expire

    Webhooks & polling

    Dashboards with a source_url auto-refresh server-side. If your downstream agent needs change detection, poll the embed URL on a cadence (every 5–15 min is typical) and diff the returned snapshot. Native webhook callbacks are on the roadmap.

    Best practices

    • Cache dashboard_url per logical dataset to avoid duplicate generation.
    • For recurring datasets, prefer source_url so the dashboard stays live.
    • Always set title — it becomes the embed page title and improves shareability.
    • Use chart_type only when your agent has strong intent — auto-selection usually wins.
    • Embed the iframe with sandbox="allow-scripts allow-same-origin" if rendering inside another agent UI.

    Billing

    Pay via Stripe Checkout — see /pricing:

    • Subscriptions — $29/mo (100 charts, $0.49 overage) or $79/mo (400 charts, $0.39 overage). Included quota resets monthly.
    • Prepaid bundles — one-time $9 / $29 / $79 / $199 for 15 / 60 / 200 / 600 credits. Stack on any subscription, never expire.
    • x402 (agents) — $0.59 USDC on Base per successful chart. No signup, agent pays automatically.

    Agents & bundles: when an agent calls /generate-chart with Authorization: Bearer tc_live_…, we draw from the account's subscription quota and prepaid bundle credits first, and only fall back to $0.59 x402 per chart once both are exhausted. Every response includes an X-Chart-Billing header (weekly, prepaid, trial, or x402) so agents can observe how they were charged.

    When weekly quota is exhausted, calls fall through to top-up credits. When both are zero, the endpoint returns 402 quota_exhausted with a buy_url pointing to /pricing#topups. Failed calls (4xx/5xx) never consume credit.

    Changelog

    • v1.1 — paid-only API. Bearer key required on every call. Weekly subscriptions + stackable top-ups. New 402 quota_exhausted response.
    • v1 — REST + A2A + email triggers, 15 chart types.
    Agent builders

    Wire TableCharts into your agent

    Get an API key, paste the one-line MCP config, or point your A2A orchestrator at /.well-known/agent-card.json. 5 free charts, no credit card.