> ## Documentation Index
> Fetch the complete documentation index at: https://docs.supaboard.ai/llms.txt
> Use this file to discover all available pages before exploring further.
> Build an interactive analytics site, then publish and share it.
# Datasites
A **Datasite** is a custom analytics site that an AI analyst builds for you out of your own data. You describe what you want in plain English; it writes the queries, designs the pages, and gives you a live site you can publish and embed.
Where a [dashboard](/dashboards/overview) is a grid of widgets you arrange yourself, a datasite is a designed page — your layout, your sections, your narrative — that you shape by talking to it. Under the hood it's a real React application with real saved queries, and you can read and edit both.
Use **Artifacts → Datasites** to find your sites. Availability depends on your workspace plan and access.
## Before you begin
You need Datasites feature access and permission to create a site. Choose an agent with access to its data, and prepare the audience, metrics, and any reference files.
Turn a brief into an interactive preview.
Review the audience and put the site live.
## Creating a Datasite
Open **Artifacts → Datasites** to find existing sites. Choose **New Artifact → Datasite**, enter a name and description, optionally select a project, and choose **Build with AI** to open the Analyst with your brief.
Use **Build Manually** if you want to start with an empty site in the editor. You need permission to create a Datasite and access to the data it will use.
### Other ways in
* Use the **Datasite** shortcut on Home, complete the prompt, and send it.
* Ask for a Datasite in an existing Analyst chat.
* Use **Create as Datasite** from a dashboard's options menu to start from its charts, tables, and KPIs. Use **Add Page** in that dialog to include more than one dashboard page.
In the Datasite editor, you can attach supporting files, select an agent, and use the **Build**, **Plan**, or **Ask** modes described below.
### Writing a good first prompt
The analyst works from what you tell it, and the first message sets the shape of everything that follows. Worth including:
* **Who it's for** — *"for our customer success team"*, *"a public status page for our customers"*
* **What sections you want** — *"a KPI row, then revenue over time, then a filterable table of accounts"*
* **How it should be filterable** — *"filter by region and plan tier"*
* **Anything visual** — *"use our brand blue, dark background"* (attach a logo and it'll use it)
You can course-correct at any point, so don't over-plan. But a prompt with structure in it saves a round trip.
## The Library
Open **Artifacts → Datasites** to browse your sites. Search by name, filter by project or ownership, and switch between **Grid** and **Table** views. Status distinguishes draft and published sites.
Open a site to work on it. Its **⋯** menu contains the editing, sharing, and management actions available to you. See [Artifacts](/artifacts/overview) for the shared library controls.
## The Editor
The editor is split: the analyst chat on the left, your datasite on the right. Drag the divider to resize.
A brand-new datasite starts with the chat filling the window and reveals the right-hand pane once the first version has built.
**Toolbar:**
| Control | What it does |
| - | - |
| Back arrow | Returns to the library |
| Title + pencil | Rename the datasite in place |
| **Share** | Invite workspace members |
| **Publish** | Make the current build live (see [Publishing](#publishing-and-embedding)) |
**Above the right-hand pane:**
| Control | What it does |
| - | - |
| **Preview / Code / Glossary** | Switch between the running site, its source, and its queries |
| **Desktop / Tablet / Phone** | Preview at different widths, with a device frame |
| Environment picker | Run the preview against a different data source mapping |
| **Variables** (key icon) | API keys and config values for the site — see [Datasite Variables](/datasites/datasite-variables) |
| **Select & edit elements** | Click something in the preview to talk about it |
| **Refresh this view** | Rebuild the preview, or refetch files and queries |
| Panel toggle | Hide or show the chat |
## Working With the Analyst
### Conversations
The analyst keeps separate conversation threads. The panel header shows the current thread's name — click it to switch threads or start a **New conversation**, and use the pencil and trash icons to rename or delete one.
* A new thread isn't created until you actually send something, and it names itself from your first message
* Opening the editor lands you in your most recently active thread
* Leaving a thread mid-turn is safe — the work continues server-side and the thread re-attaches to it when you come back
* Chats from before threads existed live on in a single adopted thread
### Modes
The chat has three modes. The mode pill sits above the message box, and the tooltip summarises them:
> *"Build writes code + glossary; Plan updates PLAN.md; Ask is read-only Q\&A"*
| Mode | What it does | Reach for it when |
| - | - | - |
| **Build** | Writes queries and code, then compiles to check its work. The default. | You want something built or changed. |
| **Plan** | Explores your data and writes a plan into `PLAN.md`. Touches no application code. | The datasite is substantial and you want to agree the shape first. |
| **Ask** | Read-only. Answers questions about the datasite and its data. | You want to understand what's there without changing anything. |
### The Plan → Build handoff
When a Plan turn finishes, a **Build this Plan** button appears on the message. Clicking it hands the plan straight to a Build turn. The editor also switches to the Code tab with `PLAN.md` open so you can read — and edit — the plan before committing to it.
`PLAN.md` renders as formatted text with an **Edit as text** link if you'd rather rewrite it by hand.
### While it works
Assistant messages show a **Thought for N steps** toggle that expands into what it actually did — every query it ran, every file it wrote. Worth opening when a result surprises you.
Turns keep running even if you close the tab; the work continues server-side and shows up in the history when it's done.
The send button becomes a **Stop** button while a turn is running. Stopping is safe — anything already finished, like a saved query or a written file, is kept.
## The Glossary
The **Glossary** is the datasite's saved-query layer. This is the concept most worth understanding, because it's what keeps a datasite honest.
> Despite the name, it is not a dictionary of business terms. Each glossary item is a **named, saved query** with an ID.
Here's the arrangement: the analyst writes a query, tests it against your database, and saves it under an ID like `revenue-by-region`. The generated page then asks for data *by that ID*. The query itself never reaches the browser — visitors to your published datasite get results, never SQL, and never credentials.
### Working with glossary items
Open the **Glossary** tab. Saved queries are listed on the left; select one to see its title, its SQL, and a **Save & Run** button that executes it and shows the result table.
Every save re-runs the query first. A query that errors won't save, so a broken glossary item can't silently ship.
### Edit with AI
The **Edit with AI** button stages that one query for the chat — a chip appears above the message box showing which item you're editing. Describe the change and send.
Scoping the edit this way matters: it constrains the analyst to that item and the components bound to it. The item keeps its ID, so every reference in the page keeps working, and the rest of your datasite is left alone.
### Filters
Glossary items can declare which columns are filterable, which is what powers the filter controls on the page.
> **A filter only works if its query actually reads the table it's declared against.** If the analyst declares a filter on a column from a table the query never joins, the filter is silently ignored — the page returns unfiltered data and the control looks broken.
If a filter isn't doing anything, that's the first thing to check. Telling the analyst *"the region filter isn't affecting the chart"* is usually enough for it to rewrite the query to join the table it needs.
## Pinning Existing Widgets In
You don't have to rebuild work that already exists. Any chart, table, or KPI can be pinned into a datasite.
From a widget's **Pin widget** popup — or the pin menu in [the Analyst](/analyst/overview) — choose the **Datasites** tab and pick a datasite. You're taken to that datasite with the widgets waiting as chips above the message box.
They ride along with your next message, so you can say where you want them: *"add these to a new section at the bottom, under a heading called Pipeline Health"*. Send an empty message and they're simply added.
> **The pinned query is used exactly as written.** It isn't rewritten, reformatted, or merged with anything — so the numbers on your datasite match the numbers you pinned, to the row. The widget keeps its type too: a line chart stays a line chart. Only the styling is rebuilt so it looks native to the datasite.
If the pinned query errors when it runs, the analyst reports the error rather than "fixing" it — the query is yours to change.
## The Code Tab
Everything the analyst writes is readable and editable.
**The file tree** has two sections:
* **Source** — the files you can edit. Components live under `components/`, one per file; configuration and styling under `lib/`. Charts are built with recharts.
* **Infra · read-only** — four files (`index.html`, `main.jsx`, `sb/client.js`, `sb/params.js`) that wire the site to your data. These are injected at build time and can't be edited.
Select a file to open it in the editor. **Copy** copies its contents; **Save** writes the file and rebuilds the preview.
> Saving rebuilds the **preview**, not the live site. Your published datasite is unaffected until you publish again.
There's no autosave and no diff view of the analyst's changes, so save deliberately — and if you're making a large hand edit, copy the original somewhere first.
## Select & Edit Elements
The most direct way to change something you can see.
Click **Select & edit elements** in the preview toolbar. A strip appears — *"Select mode on — click any element to edit it"* — and the cursor becomes a crosshair. Click anything in the preview.
Select mode switches itself off and a chip appears above the message box naming what you picked. Your next message is scoped to that element: *"make this number bigger and put the change percentage underneath it"*.
Much faster than describing which of five KPI tiles you mean.
## When a Build Fails
If the analyst writes code that doesn't compile, the preview is replaced with:
> **Build failed · preview not updated**
> Fix the errors below — your live embed still serves the last published build.
Each error names its file, line, and the offending code. The **Fix with AI** button hands all of it back to the analyst, which is almost always the right move.
A green build that then crashes at runtime shows a red strip with the error and the same **Fix with AI** button.
> A failed build never takes your published datasite down. Visitors keep seeing the last version you published.
## Environments
An **environment** remaps which data source a datasite queries, without touching its code or its queries. The usual case is pointing the same datasite at staging and at production.
Open the environment picker in the preview toolbar and choose **Manage environments**.
| Field | Notes |
| - | - |
| **Name** | e.g. `Production` |
| **Set as default environment** | Used when no environment is specified |
| **Resource Mapping** | Rows of *Original Resource* → *In This Environment* |
Resources this datasite actually queries are sorted to the top of the pickers.
**Selecting one:** the preview picker switches the preview, and adding `?environment=` to a datasite URL switches it for a viewer. That URL parameter overrides whatever the link would otherwise use.
Switching environments needs no rebuild — the same site simply queries elsewhere.
Every datasite starts with an environment named `default` that maps nothing, so it queries your original sources until you say otherwise. The default environment can't be deleted, since links that don't specify one fall back to it.
## Publishing and Embedding
### Publish
The **Publish** button is disabled until at least one preview build has succeeded — you can't publish a datasite that doesn't compile.
Clicking it opens a popover showing the datasite's address and its visibility. Publish, and the popover switches to showing the live version with a copyable URL. **Update** republishes your current preview build over the live one.
First publish also mints the datasite's own address — a subdomain named after the datasite, like `revenue-overview-x7k2p.supaboard.live` — which is what embed links use. You can put a domain you own in front of it from the same popover. Both are covered in [Datasite Custom Domains](/datasites/datasite-custom-domains).
### Public or private
The pill next to the address toggles visibility:
| Setting | Tooltip |
| - | - |
| **Public** | *"Anyone with the link can view. Click to make private."* |
| **Private** | Viewers sign in, and only people with access can open the site. |
Datasites are **private** unless you make them public.
### Sharing the link
This is the part worth getting right, because the two visibilities behave differently:
* **Public** — the copied URL includes an access token, and needs it. The link works for anyone, with no sign-in. Copy the URL exactly as given; a trimmed link won't load data.
* **Private** — the copied URL has no token. Viewers are asked to sign in — with email and password, or via **Continue with Google** / **Continue with Microsoft** — and only people with access to the Datasite can get in. The OAuth buttons don't create accounts; an email your workspace doesn't know is turned away.
Embed a datasite by putting its URL in an `