Dashboards and sharing

You can show your data to people who have no AgentDB account. AgentDB offers three ways:

• Live dashboards: totals and short lists that update by themselves. AgentDB hosts the page.
• Published views: one saved view, read-only, through an expiring link.
• Custom dashboards: a small website your AI builds, hosted by AgentDB. This is experimental.

None of them puts an API key in a web page. Each link shows only what you chose, and you can stop it at any time.

#Create a live dashboard

Ask your AI: "Make a live dashboard of my contacts by stage." It calls dashboards_create with a list of panels.

• A panel shows totals (aggregate, like records_aggregate) or a short list (query, at most 50 rows).
• A dashboard has at most 12 panels.
• A panel displays as number, bar, line or table.

The example first creates a small contact list:

{"tool": "schema_define_object", "arguments": {"name": "contact"}}

{"tool": "schema_define_field", "arguments": {"object": "contact", "name": "name", "type": "text"}}

{"tool": "schema_define_field", "arguments": {"object": "contact", "name": "stage", "type": "enum", "enum_values": ["lead", "customer"]}}

{"tool": "records_create", "arguments": {"object": "contact", "data": {"name": "Ada Lovelace", "stage": "lead"}}}

Now the dashboard:

{"tool": "dashboards_create", "arguments": {
  "title": "Contacts",
  "panels": [
    {"title": "Contacts by stage", "aggregate": {"object": "contact", "group_by": ["stage"], "metrics": [{"op": "count"}]}},
    {"title": "Latest", "query": {"object": "contact", "sort": [{"field": "created_at", "order": "desc"}], "limit": 5}, "fields": ["name", "stage"]}
  ]
}}

The answer holds two links. AgentDB shows them only once.

• page_url: a page AgentDB hosts. It is live, works on a phone and follows light or dark mode. Share it as it is.
• data_url: the same panels as JSON, for a page you or your AI design.

You can also set layout (1 to 4 columns), a panel width, and a format such as currency or percent.

#Build your own page on the data link

data_url needs no API key, and any web page can fetch it. It returns the dashboard with a marker.

For live updates, call data_url?since=<marker>&wait=1 in a loop. AgentDB answers about a second after the data changes. When nothing changes, it answers {"unchanged": true} after about 25 seconds.

async function live(dataUrl, onData) {
  let marker;
  for (;;) {
    const r = await fetch(dataUrl + (marker === undefined ? "" : "?since=" + marker + "&wait=1"));
    const j = await r.json();
    if (!j.data) throw new Error(j.error.message); // revoked, expired or refused
    marker = j.data.marker;
    if (!j.data.unchanged) onData(j.data);
  }
}

The usage part of the create answer holds a ready loop with retries. Your AI can paste it into the page.

#Share a dashboard

You choose who can read a dashboard. You set this when you create it, or later with dashboards_update.

{"tool": "dashboards_update", "arguments": {"dashboard_id": "$DASHBOARD_ID", "access": "password", "password": "violet harbour lantern"}}

Give the password to people separately. Never write it into a page.

More controls:

• Expiry: new link dashboards expire after 90 days. Set expires_in_days (1 to 365), or null for no expiry.
• Allowed origins: allowed_origins: ["https://intranet.example.com"] refuses browsers on other websites. This is not a secret, so combine it with a password or an expiry.
• New link: dashboards_rotate_token gives new links. The old ones stop at once.
• Stop it: dashboards_revoke ends the dashboard and every open page at once. Your data does not change.
• Who looks: dashboards_list shows the last time someone opened it and views per day. It stores counts only.

Owners and admins also see every dashboard in the app, under Settings → Dashboards. There you can open, renew or revoke one.

{"tool": "dashboards_list", "arguments": {}}

To change the panels, read the dashboard with dashboards_get first. Then call dashboards_update with its current version. The link stays the same.

#Publish a saved view

A saved view is a named query on one object. You can publish it read-only through a link. People see a table; pages can use its data_url.

{"tool": "views_create", "arguments": {"name": "leads", "object": "contact", "definition": {"where": {"all": [{"field": "stage", "op": "eq", "value": "lead"}]}, "fields": ["name", "stage"]}, "visibility": "workspace"}}

{"tool": "views_publish", "arguments": {"view": "$VIEW_ID", "expires_in_hours": 24}}

• The link expires after 7 days by default. expires_in_hours goes up to one year.
• access: "password" asks for a password first.
• The view runs with your permissions, now and later. It never shows more than you may see.
• fields narrows the columns further. Files show as short-lived signed links.
• views_unpublish stops the link at once.

#Custom dashboards (experimental)

A custom dashboard is a small website your AI builds: HTML, CSS, JavaScript, images and fonts. AgentDB hosts it at its own address, with live, read-only data.

How your AI builds one:

1. dashboard_sites_create with a title and a sharing mode.
2. dashboard_sites_upload with the files. index.html is required.
3. dashboard_sites_preview for a private preview (optional).
4. dashboard_sites_publish to make a version live. Publish an older version to roll back.

{"tool": "dashboard_sites_create", "arguments": {"title": "Sales team dashboard", "mode": "link_password", "password": "violet harbour lantern 42"}}

Sharing modes:

The page reads its data from sources declared in manifest.json, such as fetch("/_data/pipeline"). It cannot call other servers or load outside scripts. Bundle any chart library into the package.

See Approvals and the AgentHub for how a person approves a request.