# Manage Organizations
Source: https://docs.wisdom.ai/access-management/manage-organizations



This guide explains how to use the Organizations manager to create and maintain isolated environments within your tenant. Organizations ensure full data separation, meaning that connections, domains, users, dashboards, and agents are kept entirely independent across different environments.

## Before you start

To perform these tasks, you must have **Site Administrator** permissions. Regular users or organization-level admins cannot access the global Organizations manager.

Read the [Access Management](/manage-account/access-management) guide to learn more about roles and permissions.

## Create a new organization

New organizations are provisioned by Site Administrators through the platform. To do this, follow the steps below:

1. Sign in to WisdomAI as a Site Administrator.
2. Click the **Organizations** icon in the left-hand navigation menu.
3. Click the **Add Organization** option.

<Frame>
  <img alt="Create New Organization UI" />
</Frame>

4. In the modal that opens, under **Organization Details**:

   a. Enter the **Organization Name** (e.g., "Finance-Dept").

   b. Define the **URI** (e.g., `finance`). This creates a unique access point: `https://try.askwisdom.ai/organizations/finance`.

   c. Add **Organization Admins** by entering their email addresses.

   d. (Optional) Expand **Advanced Options** to define **Allowed email domains**.

   <Tip>
     The **Allowed email domains** setting acts as a security gate. By specifying a domain (e.g., `company.com`), you ensure that only users with official company emails can be added to the organization, preventing accidental access by external or personal accounts.
   </Tip>

5. Click **Create Organization**.

<Note>
  If you encounter any issues during provisioning, please contact [the WisdomAI support team](/manage-account/contact-support) for assistance.
</Note>

## Manage existing organizations

Once created, you can manage organizations directly from the dashboard using quick-access icons.

### Modify settings and access

* **Edit Details**: Click the **three-dot menu (...)** on an organization tile and select **Edit** to update the name, URI, or administrative owners.

<Frame>
  <img alt="Edit Organizations modal" />
</Frame>

* **Access Domains**: Click the **monitor icon** to configure AI domains specific to that organization.
* **Manage Connections**: Click the \*\*sync/connections \*\*(arrows)**icon**  to set up or modify data source integrations for that environment.

<img title="Manage Organization Icons" alt="Manage Organization Icons" />

<img title="Manage Organization Icons" alt="Manage Organization Icons" />

### User administration

Click the **person icon** to open the user management view:

* **Invite Users**: Click **Invite Users** to grant access to the specific organization.
* **Export List**: Click **Export to CSV** to download a record of all users assigned to the organization.

<Frame>
  <img alt="Manage Organization Icons" />
</Frame>

### Archive an organization

If an environment is no longer needed, you can deactivate it to prevent further access.

1. Click the **three-dot menu (...)** on the organization tile.
2. Select **Archive organization**.
3. Confirm the action in the dialog box.

<Frame>
  <img alt="Archive Organization" />
</Frame>

<Note>
  Archiving deactivates the organization immediately, meaning users will no longer be able to log in. However, your data is **not deleted**; it remains securely stored in case you need to reactivate the environment in the future.
</Note>

## Next steps

<CardGroup>
  <Card icon="user-shield" href="/manage-account/row-level-access-control/row-level-access-control" title="Row-Level Access Control">
    Learn how to restrict data access at the row level for specific users or roles.
  </Card>

  <Card icon="key" href="/manage-account/access-management" title="Access Management">
    Control user permissions and manage access to platform features and data.
  </Card>

  <Card icon="database" href="/getting-started/connect-data-sources/supported-data-sources" title="Supported Data Sources">
    Explore the full list of databases and platforms you can connect to the system.
  </Card>

  <Card icon="brain" href="/getting-started/how-wisdom-ai-works" title="How WisdomAI Works">
    Understand the core concepts and architecture behind the platform's data analysis capabilities.
  </Card>

  <Card icon="rocket" href="/setting-up-wisdom-ai/basic-tutorial-connect-and-test" title="Basic Tutorial: Connect and Test">
    Walk through the initial setup to connect a data source and run your first query.
  </Card>

  <Card href="/setting-up-wisdom-ai/manage-domains/understand-domains" title="Manage Domains">
    Configure how WisdomAI accesses data, understands your business context, and evaluates response accuracy.
  </Card>
</CardGroup>


# Use the Deep Analysis Functionality
Source: https://docs.wisdom.ai/advanced-features/deep-analysis



Use the Deep Analysis feature to investigate complex, open-ended questions, such as "Why did our revenue spike last quarter?". The feature automates the investigation by creating a multi-step analysis plan, executing it, and generating a comprehensive report with its findings.

This tutorial teaches you how to investigate a data anomaly, refine the analysis plan, and interpret the final report to understand its root cause.

<Note>
  The Deep Analysis feature is currently in beta and is available to all Admin users.
</Note>

## Perform a Deep Analysis

Follow the steps below to run a complete investigation, from enabling the feature to exploring the final report.

### Step 1: Enable Deep Analysis mode

Before asking a question, enable Deep Analysis mode in the chat interface.

1. In a new or existing chat, locate the **Deep Analysis** toggle.
2. Click the toggle to enable it. Once enabled, all subsequent questions you ask in this chat will use Deep Analysis until you disable it.

<img alt="Screenshot showing the Deep Analysis feature enabled" />

### Step 2: Ask an open-ended question

With Deep Analysis enabled, ask a question that requires investigation rather than a simple answer. These questions often start with "Why," "Investigate," or "What are the main drivers of...".

For example, you could ask: `Investigate why there was a spike in Q4 2023 revenue compared to Q3 2023`.

<img alt="Screenshot showing the question sent" />

### Step 3: Review and refine the Analysis plan

After you submit your question, Deep Analysis will not immediately run the full investigation. Instead, it generates a proposed plan outlining the steps it will take to answer your question.

This is your opportunity to guide the analysis:

* **Review the steps**: Read through the proposed plan to ensure it aligns with your goals.
* **Modify the plan**: You can ask the system to change the plan using natural language. For example, you can remove steps ("don't do these last five steps") or add new ones ("also do a competitive analysis").
* **Approve the plan**: If the plan looks correct, type `continue with the investigations` to begin the analysis.

<img alt="GIF showing how you can modify the plan before running the analysis" />

### Step 4: Monitor the investigation

Once you approve the plan, the system begins executing the investigation. This process can take several minutes. A sidebar will appear, showing the real-time progress of each step in the analysis plan.

<Check>
  You can navigate away from the chat, start a new one, or continue with other work; the analysis will continue running in the background. Closing the browser tab will not interrupt the process.

  You can always return to the chat to check the progress. The analysis status is saved in a persistent card that you can click to reopen the progress view.
</Check>

<img alt="Screenshot showing the report" />

### Step 5: Explore the final report

When the investigation is complete, Deep Analysis compiles the findings into a detailed report. You can open the report from the chat, and it will be displayed in the side panel. The report typically includes:

* **An executive summary**: A high-level overview of the main findings.
* **Key findings**: Detailed points explaining the results of the investigation.
* **Detailed Analysis:** This section presents the in-depth results of the investigation, which can be broken down into various sub-topics like time trends, deal volume, or lead source effectiveness.
* **Visualizations**: Charts and tables embedded within the report to support the findings.
* **Conclusions and Actionable Insights:** This section synthesizes the key findings into a clear conclusion and provides practical takeaways.
* **Follow-up data analysis:** The report suggests new questions to guide your next steps.

You can continue the conversation by asking follow-up questions about the report, such as `generate a shorter one page version of the report`, to refine the insights further.

<img alt="GIF showing a request to generate a one-page report" />

## Use case examples

Deep Analysis is ideal for situations where a single data point isn't enough to understand the full picture.

### Investigating a performance spike

This is a primary use case for conducting root cause analysis when a key metric changes unexpectedly.

* **Scenario**: You notice a sudden increase in user engagement for a specific feature and need to understand the cause.
* **Question**: `Investigate the key drivers for the spike in user engagement for the 'new dashboard' feature last month.`
* **Outcome**: Deep Analysis generates a report identifying the primary causes, such as a recent marketing campaign, a new integration partner driving traffic, or a specific segment of users heavily adopting the feature. The report would include charts breaking down engagement by user segment and traffic source.

### Understanding complex business trends

Use Deep Analysis for exploratory analysis when the factors influencing a trend are not immediately apparent.

* **Scenario**: Your quarterly report shows an increase in customer churn, but the high-level numbers don't explain why it's happening.
* **Question**: `What are the primary factors contributing to customer churn in Q2?`
* **Outcome**: The system creates a plan to segment churned customers by subscription plan, region, product usage, and signup date. The final report reveals that customers on a specific plan who do not adopt a key feature within their first 30 days are the most likely to churn, providing actionable insight for the product team.

## Next steps

<CardGroup>
  <Card title="Agents" icon="robot" href="/setting-up-wisdom-ai/agents/agents">
    Automate data monitoring and receive proactive alerts when specific conditions are met.
  </Card>

  <Card title="Enhance Analysis with Business Knowledge" icon="lightbulb" href="/improve-wisdom-ai-responses/enhancing-data-analysis-with-custom-business-context">
    Improve analysis by providing custom business definitions, synonyms, and other contextual information.
  </Card>
</CardGroup>


# Python Interpreter Tool
Source: https://docs.wisdom.ai/advanced-features/python-interpreter-tool



Use the Python Interpreter tool to go beyond SQL and perform advanced data science operations such as forecasting, regression, clustering, and mathematical calculations directly from natural language in Chat. When you ask a question that requires computation beyond what SQL can answer, WisdomAI automatically generates Python code, executes it securely, and visualizes the result.

This guide explains how to enable the tool, what types of analysis it supports, and how to get the best results.

## How it works

When you ask a question that requires advanced computation, WisdomAI follows this process:

1. **Retrieves data**: If the analysis needs data from your database, WisdomAI first queries it using SQL.
2. **Generates Python code**: WisdomAI translates your natural-language instruction into Python code.
3. **Visualizes the result**: The result is automatically visualized as a chart or table—you do not need to write any plotting code.

## Enable or disable the tool

Before asking a question, make sure the Python Interpreter tool is enabled in the chat interface.

1. Open a **Chat** in WisdomAI.
2. Locate the **experimental tools** selector in the chat input area.
3. Toggle **Python Interpreter** on or off.

<Frame>
  <img alt="Image" />
</Frame>

<Note>
  Your preference is saved and persists across sessions. When enabled, WisdomAI will use the tool automatically when your question requires Python-level analysis. When disabled, only SQL-based analysis is available.
</Note>

## What you can do

Perform the following data science tasks and advanced transformations directly within your chat sessions:

### Mathematical calculations

Ask any arithmetic or mathematical question, and WisdomAI will compute it with Python rather than relying on approximations.

* `What is the compound annual growth rate of revenue from 2020 to 2024?`
* `Calculate the standard deviation of deal sizes across all closed-won opportunities.`

### Time-series forecasting

Forecast future values using statistical models. WisdomAI selects the appropriate method based on your data.

**Example questions:**

* `Forecast monthly revenue for the next 12 months.`
* `Predict weekly active users for Q3 based on historical trends.`

<Frame>
  <img alt="Image" />
</Frame>

The result automatically includes both original and forecasted values in a single visualization, so you can compare them side by side.

### Regression Analysis

Fit regression models to understand relationships between variables or extrapolate trends.

**Example questions:**

* `What is the relationship between marketing spend and revenue?`
* `If we increase headcount from 50 to 100 in steps of 5, what is the projected output?`

<Frame>
  <img alt="Image" />
</Frame>

### Clustering

Group data points into clusters to discover natural segments in your data.

<Frame>
  <img alt="Image" />
</Frame>

<Frame>
  <img alt="Image" />
</Frame>

### Data manipulation and transformation

Perform pandas-style operations that SQL cannot express, such as pivoting, rolling windows, or custom row-level logic.

**Example questions:**

* `Calculate the 7-day rolling average of daily signups.`
* `Merge the sales and returns tables on order_id and compute net revenue per product.`
* `Pivot the data so each region becomes a column with total sales as values.`

## Available Python libraries

Code generated by WisdomAI runs in a secure, sandboxed environment. Only a curated set of Python libraries is available for import. Any attempt to import a module outside of this list will be blocked.

The following libraries are allowed:

`collections` `csv` `datetime` `functools` `itertools` `json` `math` `numpy` `pandas` `prophet` `random` `re` `scipy` `sklearn` `statsmodels` `string`

If you need a module that is not listed above, contact [the WisdomAI support team](/manage-account/contact-support) for assistance.

## Tips for best results

* **Be specific about the analysis you want.** Instead of "analyze sales," ask "forecast monthly sales for the next 6 months using the last 2 years of data." Specificity helps WisdomAI choose the right method and parameters.
* **Fetch data first, then analyze.** For data science tasks, WisdomAI follows a two-step process: first, query data via SQL, then analyze it with Python. If you notice missing data, ask for a follow-up to retrieve the full dataset before re-running the analysis.
* **Ask to adjust parameters.** After a forecasting or regression result, you can ask WisdomAI to change the method or tune parameters. For example: "Redo the forecast using ETS with multiplicative seasonality" or "Try Ridge regression with alpha=0.5."
* **Use follow-up questions.** The result persists in your conversation. You can ask follow-up questions like "Now filter this to only show Q4" or "Add a trend line to the existing data."

## Use case examples

### Forecasting revenue

* **Scenario**: You need to forecast next quarter's revenue using historical monthly data.
* **Question**: `Forecast monthly revenue for the next 3 months based on the last 2 years of data.`
* **Outcome**: WisdomAI first queries your revenue data, then runs a SARIMAX or ETS forecast, and presents both the historical and forecasted values in a single line chart.

### Segmenting customers

* **Scenario**: You want to identify natural customer segments for a marketing campaign.
* **Question**: `Cluster our customers into groups based on total spend and order frequency. Suggest the best number of clusters.`
* **Outcome**: WisdomAI queries customer metrics, runs K-Means with silhouette scoring to determine the optimal number of groups, and presents a scatter plot with color-coded clusters.

### What-if analysis

* **Scenario**: You want to understand how increasing ad spend might affect conversions.
* **Question**: `Based on historical data, if we increase ad spend from $10K to $50K in $5K steps, what are the projected conversions?`
* **Outcome**: WisdomAI fits a linear regression on historical ad spend vs. conversions, extrapolates over the specified range, and shows both the original data and projected values.

## Next steps

<CardGroup>
  <Card icon="magnifying-glass-chart" href="/advanced-features/deep-analysis" title="Deep Analysis">
    Investigate complex, multi-step questions with automated research plans and detailed reports.
  </Card>

  <Card icon="chart-bar" href="/advanced-features/visualization-types-and-properties" title="Visualization Types">
    Explore all available chart types and how to customize your data presentation.
  </Card>

  <Card icon="lightbulb" href="/using-wisdom-ai-everyday/ask-better-questions" title="Ask Better Questions">
    Learn how to phrase questions for the best and most accurate results.
  </Card>

  <Card icon="table-columns" href="/improve-wisdom-ai-responses/build-dashboards" title="Build Dashboards">
    Pin analysis results to dashboards for ongoing monitoring and sharing.
  </Card>
</CardGroup>


# Visualization Types and Properties
Source: https://docs.wisdom.ai/advanced-features/visualization-types-and-properties



This guide covers the visualization features within WisdomAI's **Dashboards and Chats**. It explains how to analyze trends, compare categories, and adjust data display settings.

The following sections describe:

* The catalog of available **chart types** to represent your data visually.
* Options for **switchable encodings** that allow you to adjust axis assignments, filters, and aggregations.
* Built-in **interaction options** to customize queries and validate results.
* Key **accessibility features** designed to make Dashboards approachable for all users.

## Graph / Chart Catalog

WisdomAI's Dashboards support a variety of chart types to represent data insights effectively. Users can select the desired chart type through a dropdown menu in the **Editor** tab.

<img alt="Image showing the editor tab charts list" />

### Available chart types

| Chart Type                      | Feature                                                                                                                                                                                                                                                                                       |
| :------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Table**                       | Displays raw data in a structured format, ideal for precise values and detailed comparisons.                                                                                                                                                                                                  |
| **Pie Chart**                   | Best for showing proportions within a whole, where each slice represents a percentage of the total. (Consider using for 5-7 slices maximum.)                                                                                                                                                  |
| **Funnel Chart**                | Illustrates how values progress through different stages of a sequential process, often used to visualize conversion or attrition rates.                                                                                                                                                      |
| **Bar Chart**                   | Useful for comparing quantities across discrete categories, with the length of the bars representing the values.                                                                                                                                                                              |
| **Bar Chart (stacked)**         | Displays multiple data series in a single bar, where segments within the bar show the contribution of each part to the whole. Useful for comparing sub-categories and their cumulative totals.                                                                                                |
| **Bar Chart (100% stacked)**    | Similar to a stacked bar chart, but each bar represents 100% of a category, with segments showing the percentage contribution of subcategories. Ideal for showing part-to-whole relationships and how proportions change over time. (Be cautious as overall totals are not explicitly shown.) |
| **Column Chart**                | Visually represents numerical values using vertical columns. Ideal for comparing discrete categories, often with the height of the column corresponding to the value.                                                                                                                         |
| **Column Chart (stacked)**      | Presents multiple data series as vertical bars, with segments stacked to show their cumulative sum. Aids in comparisons between categories over time or across different groups.                                                                                                              |
| **Column Chart (100% stacked)** | Compares multiple measures by stacking bars vertically, where each segment represents the percentage of the overall category total. Useful for showing the distribution of components within a whole at a specific point in time or across time.                                              |
| **Area Chart (stacked)**        | Shows data as an area under a line that connects data points, with multiple series stacked on top of each other. Useful for displaying the contribution of different components to a whole while showing overall patterns and cumulative trends over time.                                    |
| **Area Chart**                  | Visualizes quantitative data and shows how values change over time, with the area between the line and the baseline filled with color. Ideal for emphasizing trends and the magnitude of change.                                                                                              |
| **Line Chart**                  | Ideal for displaying trends over time or across continuous measurements, showing how data changes and identifying patterns. (Excellent for time-series data.)                                                                                                                                 |
| **Map**                         | Transforms geographic data into visual insights by displaying information across different regions, countries, or territories. Useful for visualizing spatial patterns and distributions.                                                                                                     |

These visualization options enable users to tailor the presentation of data to their specific analytical needs. Therefore, selecting the optimal chart depends on your data, the message you want to convey, and your audience. Always consider what insights you want to highlight before picking a chart type.

## Switchable encodings

Within the **Editor** tab, users can customize data encodings to refine their visualizations, for example:

* **Axis Assignment** – Drag and drop data columns to assign them to the X and Y axes\
  *(e.g., "Region" on X-axis, "Total Revenue SUM" on Y-axis)*.
* **Data Filtering** – Apply filters to focus on specific data subsets\
  *(e.g., "Stage Label: Closed Won")*.
* **Aggregation Functions** – Use SUM, AVG, etc., to aggregate numerical data as needed.

These features allow for dynamic adjustment of visualizations to highlight the most relevant insights.

<img alt="Image showing encoding options" />

## Interaction options

WisdomAI provides interactive elements to enhance user engagement and data exploration:

* **Editable SQL** – Modify the generated SQL queries in the **SQL** tab to correct or fine-tune results.
* **Feedback Mechanism** – Give a thumbs up or down to improve future AI responses.
* **Review & Validation** – Mark queries as reviewed to confirm accuracy in team workflows.

These interaction options support iterative refinement and validation of data analyses.

<img alt="Image showing the SQL code edition window" />

## Accessibility notes

WisdomAI emphasizes accessibility to ensure a wide range of users can effectively engage with Dashboards:

* **Natural Language Interface:** Ask questions using plain English to generate data queries.
* **Visual Configuration Tools:** Use drag-and-drop components in the Widget Editor to configure visuals without writing code.
* **Collaborative Integrations:** Access insights directly from platforms like Slack or Teams, supporting seamless workflows.
* **Color Accessibility:** WisdomAI Dashboards meet WCAG 2.1 AA contrast requirements, ensuring chart colors are distinguishable for users with color vision deficiencies. You can also prompt the AI to adjust chart colors to better suit your needs.

These features aim to make data exploration more inclusive and user-friendly for both technical and non-technical users.

## Next steps

<CardGroup>
  <Card title="Dual-Axis Charts" icon="chart-mixed" href="/product-updates/february-2026/dual-axis-charts">
    Plot two metrics with different scales on the same chart.
  </Card>

  <Card title="Build Dashboards" icon="table-cells-large" href="/improve-wisdom-ai-responses/build-dashboards">
    Compile your favorite charts and visualizations into a shareable dashboard.
  </Card>
</CardGroup>


# Chat 2.0
Source: https://docs.wisdom.ai/chat/overview



The new and improved WisdomAI chat experience: ask in plain language, pick a reasoning mode, follow the work, and turn answers into reports, dashboards, and agents.

Chat is where you ask questions about your data in plain language. You pick a domain, type a question, and WisdomAI plans the analysis, runs it against your governed data, and answers with tables, charts, and explanations you can inspect step by step.

<Note>
  This page describes **Chat V2**, the new chat experience that is now the default for everyone. It replaces the Classic and Deep Analysis modes: Classic chats still open, but new conversations use the experience described here.
</Note>

## Ask a question

1. **Start a new chat.** Click **New chat** in the sidebar and pick the domain that owns the data you're asking about.
2. **Type your question.** Ask the way you'd ask a colleague: "What was revenue by region last quarter?" For phrasing that gets better answers, see [Ask Better Questions](/using-wisdom-ai-everyday/ask-better-questions).
3. **Follow the work.** The answer streams in along with what the AI is doing. For multi-step questions you'll see its plan as a to-do list that checks off as it progresses.

While an answer is running you can press the **stop** button to cancel it, or keep typing: messages you send mid-answer are queued and handled next. You can also **edit** a question you already asked, or **retry** the last one.

## Choose a mode

The mode selector under the chat input controls how much reasoning your question gets:

| Mode                   | What it's for                                                                                                                            |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Thinking** (default) | Dynamic reasoning. Best for most questions.                                                                                              |
| **Lite**               | Lightweight mode for easy queries and quick answers.                                                                                     |
| **Expert**             | Highest reasoning, for the hardest questions and complex analysis. Expect it to take longer, go deeper, and often produce a full report. |

<img alt="Image showing the choose mode dropdown" />

<img alt="Image showing the choose mode dropdown" />

A conversation's mode is fixed after the first message, so start a new chat to switch modes.

<Note>
  The earlier **Deep Analysis** and **Classic** modes are deprecated. For the long-running, open-ended investigations you used Deep Analysis for, use **Expert** — it runs inside the normal chat flow, so you can watch the plan progress and answer clarifying questions along the way.
</Note>

## When WisdomAI asks you a question

If your question is ambiguous, the AI asks instead of guessing. A clarification appears just above the chat input with the likely interpretations as clickable options. Click one and the analysis continues immediately, or type your own answer if none of the options fit.

## See how an answer was produced

Every answer shows its work. Click the activity indicator on a message to open the **AI Workstream** panel: a step-by-step list of what ran. Click any step to see its detail, including the exact **SQL** or **Python** that executed, the context it used, and the output table it produced. If web search is enabled for the domain, searches and fetched pages show up here too.

This is the fastest way to verify a number before you rely on it.

## Work with answers and artifacts

Results open as tabs in a side panel next to the conversation:

* **Charts** can be opened, restyled, and exported.
* **Tables** support instant [filters](/dashboards/instant-filters), so you can narrow a result in place without re-asking.
* **Files** referenced in the analysis, including PDFs and images, preview in place.

Tables and charts carry thumbs up/down buttons. Rating an answer, especially explaining a thumbs-down, helps your admins improve the domain's context.

## Reports

For questions that deserve more than a table, the AI writes a report. An **Open report** card appears in the conversation; click it to watch the report stream in, section by section, in its own panel. From the report's **Share** menu you can:

* **Export as PDF** or **Word (DOCX)**
* **Share via link**, so teammates can open the report directly

Expert mode produces reports most often, but any mode can generate one when the question calls for it.

## Bring your own context

* **Attach files** from the **+** button: spreadsheets and CSVs, PDFs, images, and most text formats. Ask questions across them together with your connected data. See [Use File Attachments in Chat](/improve-wisdom-ai-responses/attach-files-to-chat).
* **Reference a domain file** from the same menu to pull an existing dataset or document into the conversation without re-uploading it.
* **Paste** images or code straight into the input.

## Type less

* Type **/** to insert a [skill](/setting-up-wisdom-ai/manage-domains/skills) your team has defined for recurring analysis patterns.
* Gray **ghost text** suggests a completion as you type; press **Tab** to accept it.
* Click the microphone to **dictate** your question instead of typing it.

## Long-running questions

Deep questions take time. When a turn runs long, a **Notify me when complete** option appears above the input; enable it and your browser alerts you when the answer is ready, so you can work elsewhere in the meantime.

## Manage a conversation

* **Share** the conversation from the top bar and control who can open it.
* **In this chat** lists every question asked, so you can jump around long conversations.
* From a message you can **copy a direct link** to it or **fork the chat** from that point to explore a different direction.
* Rename, pin, duplicate, or delete the chat from its options menu.

## Turn answers into assets

A good answer shouldn't stay buried in a conversation:

* **Add to dashboard** pins the result where your team will see it refreshed. See [Turn Answers into Dashboards](/using-wisdom-ai-everyday/turn-answers-into-dashboards).
* When a question implies a recurring cadence ("every Monday", "each month"), chat offers to create an **Agent** that runs it on schedule and delivers the result.
* When the AI learns something about your business worth keeping, it can propose saving it as domain **knowledge** for users with domain edit access to approve.

## Next steps

<CardGroup>
  <Card title="Ask Better Questions" icon="question" href="/using-wisdom-ai-everyday/ask-better-questions">
    Build sharper natural-language questions to get more accurate answers.
  </Card>

  <Card title="Turn Answers into Dashboards" icon="book-open" href="/using-wisdom-ai-everyday/turn-answers-into-dashboards">
    Compile key insights and visualizations into a shareable, narrative-driven report.
  </Card>
</CardGroup>


# Instant Filters
Source: https://docs.wisdom.ai/dashboards/instant-filters



Narrow any results table in place. Filters apply in your browser, last for your session, and never change the underlying query.

Results tables in WisdomAI have built-in filters. Pick the values you want to keep in a column, and the table narrows immediately. Nothing is re-queried, and nothing you have shared changes: the filters apply only to your view and reset when you leave the page.

Reach for them when the answer is right but the table is too broad, like when you want one region out of the twenty in the result.

## Filter a column

1. **Open the column menu.** Hover over a column header and click the menu icon.
2. **Choose Filter values.** A checklist opens with every value in the column and a count of rows for each. Use the search box to find values in long lists. `(Blank)` matches empty cells.
3. **Tick the values to keep.** The table updates as you select. **Select all** and **Select none** flip the whole list at once.

A funnel icon marks each filtered column, and a summary bar above the table shows how many filters are active. **Reset** on the summary bar clears everything at once.

## Hide a column

The same column menu has a **Hide column** option. At least one other column must be visible before you can hide one.

## What these filters never touch

* The underlying query, the saved answer, and the dashboard stay exactly as they were.
* Nobody else sees your filters. Two people can look at the same table and each keep their own view.
* Nothing persists. Refresh the page and the table returns to its full state.

<Tip>
  This makes instant filters safe to use aggressively. There is no way to break a shared dashboard or a saved answer with them.
</Tip>

## Limits

* Filters work on the rows loaded in your browser, up to 10,000.

## Next steps

<CardGroup>
  <Card title="Build Dashboards" icon="table-layout" href="/improve-wisdom-ai-responses/build-dashboards">
    Arrange widgets, add summaries, and prepare a dashboard for sharing.
  </Card>

  <Card title="Chat" icon="message" href="/chat/overview">
    Ask questions about your data, and WisdomAI analyzes your governed data to provide answers.
  </Card>
</CardGroup>


# Organize a Dashboard with Tabs
Source: https://docs.wisdom.ai/dashboards/tabs



Split a dashboard into named tabs, move widgets between them, and share links that open on a specific tab.

Tabs split a single dashboard into named views. Instead of one long page of widgets, or several near-copies of the same dashboard, you can give each audience or topic its own tab, say an overview for leadership and a pipeline deep dive for sales ops.

Everyone who can open the dashboard can switch between its tabs. Adding, renaming, reordering, and deleting tabs requires editor access to the dashboard.

## Add a tab

1. **Open a dashboard you can edit.** Click **Dashboards** in the sidebar and select the dashboard.
2. **Click + next to the tab bar.** The first time you add a tab, the widgets already on the dashboard are collected into an **Overview** tab, and your new tab appears beside it. After that, each click adds one empty tab.
3. **Name the tab.** Click the tab's name and type over it. You can rename a tab at any time the same way.

<Note>
  The tab bar appears once a dashboard has two or more tabs. A dashboard with a single tab looks the same as it always did.
</Note>

## Put widgets on tabs

New widgets are added to the tab you are currently viewing. To rearrange existing widgets, open a widget's menu and choose:

* **Move to tab** to place the widget on another tab.
* **Clone to tab** to copy it, which is useful when two audiences want the same chart alongside different neighbors.

## Reorder or delete tabs

Drag a tab left or right to reorder it.

To delete a tab, click the **×** on the tab and confirm. Deleting a tab removes the widgets on that tab from the dashboard draft, so move any widgets you want to keep first. A dashboard always keeps at least one tab, so the delete option is only available while more than one exists.

## Share a link to a specific tab

The active tab is part of the page URL. Copy the URL while viewing a tab, and anyone who opens the link lands on that exact tab. They still need access to the dashboard to see it.

## Good to know

* Existing dashboards are unchanged until the first time someone edits tabs on them.
* Dashboard filters are shared across the whole dashboard. A filter you set applies on every tab, not only the tab where you set it.

## Next steps

<CardGroup>
  <Card title="Build Dashboards" icon="table-layout" href="/improve-wisdom-ai-responses/build-dashboards">
    Arrange widgets, add summaries, and prepare a dashboard for sharing.
  </Card>

  <Card title="Share Dashboards and Set Access Control" icon="lock" href="/using-wisdom-ai-everyday/share-dashboards-and-set-access-control">
    Control who can view or edit each dashboard.
  </Card>
</CardGroup>


# Deployment Models
Source: https://docs.wisdom.ai/deployment/deployment-models



This guide details WisdomAI's three deployment models, helping you select the best path based on your organization's security, data residency, and infrastructure requirements.

<Columns>
  <Card title="Cloud-Prem" icon="server" href="#cloud-prem">
    Managed service, deployed inside your own cloud account (AWS, GCP, or Azure).
  </Card>

  <Card title="Customer On-Prem" icon="shield-check" href="#customer-on-prem">
    Full stack deployed on infrastructure you own, not a hyperscaler.
  </Card>

  <Card title="SaaS Hosted" icon="cloud" href="#saas-hosted">
    WisdomAI-managed cloud service. The fastest time-to-value, with zero infrastructure to run.
  </Card>
</Columns>

## Cloud-Prem

**Model:** Managed service, deployed inside your own cloud account

**Best for:** Teams that need data residency and cloud-account isolation while still letting WisdomAI operate the platform.

### Overview

In the Cloud-Prem model, your WisdomAI tenant is deployed as a managed service, isolated within your own cloud account on AWS, GCP, or Azure. Your data stays inside your cloud boundary; WisdomAI retains remote access to deliver updates and patches.

Operating this model is a shared responsibility: WisdomAI operates the platform itself, while provisioning of the underlying cloud resources within your account remains governed by you.

### Advantages

* **Strict data residency:** Data never leaves your organizational boundaries or your chosen cloud account.
* **Cloud spend utilization:** Apply your existing AWS, GCP, or Azure spend commitments to offset hosting costs.
* **Full operational visibility:** Retain access to all raw logs for compliance and security auditing.

### Supported cloud environments

| Cloud | Isolation                                                                  |
| :---- | :------------------------------------------------------------------------- |
| AWS   | Deployed inside your VPC; compatible with Service Control Policies (SCPs). |
| GCP   | Deployed within your project; compatible with VPC Service Controls.        |
| Azure | Deployed within your VNet; integrated with Azure Policy.                   |

### Infrastructure layer

Cloud-Prem runs on a cloud provider and uses that cloud's managed primitives:

* **Object store:** the cloud's managed object storage (e.g. S3, GCS, Azure Blob).
* **PostgreSQL:** the cloud's managed Postgres (e.g. RDS, Cloud SQL, Azure Database for PostgreSQL).

This is the defining difference from Customer On-Prem, which runs on infrastructure you own rather than a hyperscaler.

### Red Hat OpenShift

WisdomAI runs natively on Red Hat OpenShift Container Platform for enterprises that standardize on OpenShift and require every application to conform to its hardened security model. OpenShift is a platform choice rather than a separate deployment model: on Cloud-Prem, it's supported via managed OpenShift (Amazon ROSA, Azure ARO) in your cloud account.

### Access & identity

These are two separate layers: a load balancer handles network traffic, and the identity provider handles authentication and authorization:

* **Network ingress:** traffic enters through a customer-controlled load balancer, kept local to your cloud environment.
* **Identity & access:** BYO IdP (Okta / Entra ID) enforces enterprise SSO and RBAC.

## Customer On-Prem

**Model:** Full stack deployed on infrastructure you own

**Best for:** Strategic enterprise deals with a hard requirement to run entirely on customer-owned infrastructure.

### Overview

In the Customer On-Prem model, the complete WisdomAI stack runs on your own infrastructure, not a hyperscaler, and not WisdomAI's own infrastructure. You control upgrade timing, and nothing is stored outside your environment. This option is reserved for strategic enterprise deals.

### Infrastructure layer

The defining difference from Cloud-Prem is the infrastructure layer. Customer On-Prem does not run on AWS, GCP, or Azure. Because there are no cloud-managed primitives to rely on, you provide your own:

* **Object store:** your own object storage.
* **PostgreSQL:** your own Postgres instance for metadata and audit logs.

### Compute

Kubernetes-based infrastructure running the Core Engine, Context Engine, Metadata Extractor, and Chunker/Indexer.

### Upgrades

Updates are delivered over-the-air, but you control when they are applied, upgrade timing is in your hands rather than WisdomAI's.

### Red Hat OpenShift

WisdomAI runs natively on Red Hat OpenShift Container Platform for enterprises that standardize on OpenShift and require every application to conform to its hardened security model. OpenShift is a platform choice rather than a separate deployment model, set up on your on-prem datacenter.

### Access & identity

These are two separate layers: a load balancer handles network traffic, and the identity provider handles authentication and authorization:

* **Network ingress:** traffic enters through a customer-controlled load balancer, kept local to your environment.
* **Identity & access:** BYO IdP (Okta / Entra ID) enforces enterprise SSO and RBAC.

### Data handling

Nothing is stored outside the customer environment. WisdomAI operates under Zero Data Retention (ZDR) agreements with model providers (e.g. OpenAI, Anthropic).

## Cloud-Prem & Customer On-Prem Shared Capabilities

These capabilities apply equally to Cloud-Prem and Customer On-Prem:

* **Bring Your Own Identity Provider (BYO IdP):** enterprise SSO and RBAC via your Okta or Entra ID.
* **Bring Your Own LLM (BYO-LLM):** on-prem or private-cloud model endpoints, with no hard dependency on any single model provider.
* **OpenSearch:** a single system providing both the lexical index and vector search. It is the vector store, not a separate component.
* **PostgreSQL:** metadata and audit logs.
* **Data residency:** no customer data leaves their controlled environment.
* **Encryption:** AES-256 at rest, TLS 1.2+ in transit.

## SaaS Hosted

**Model:** WisdomAI-managed cloud service

**Best for:** Teams that want the fastest time-to-value with zero infrastructure to run.

### Overview

In the SaaS Hosted model, WisdomAI runs and operates the entire platform for you. There is no infrastructure for your team to provision, patch, or monitor. WisdomAI handles upgrades, scaling, and operations.

This is the fastest path to production and the lowest operational burden of the three deployment options.

### What WisdomAI manages

* All compute, storage, and networking
* Upgrades and patching (delivered continuously)
* Scaling and availability
* Monitoring and operations

### Security

* **Encryption:** AES-256 at rest, TLS 1.2+ in transit.
* **Model access:** WisdomAI operates under Zero Data Retention (ZDR) agreements with model providers (e.g. OpenAI, Anthropic), so prompts and completions are not retained by those providers.

### When to choose SaaS Hosted

Choose SaaS Hosted when you want to evaluate or adopt WisdomAI quickly and do not have a requirement to keep the deployment inside your own cloud account or infrastructure. If data residency or infrastructure ownership is a hard requirement, see [Cloud-Prem](#cloud-prem) or [Customer On-Prem](#customer-on-prem).

## Deployment models at a glance

|                                | Cloud-Prem                                                                          | Customer On-Prem                            | SaaS Hosted       |
| :----------------------------- | :---------------------------------------------------------------------------------- | :------------------------------------------ | :---------------- |
| Where it runs                  | Your hyperscaler account (AWS/GCP/Azure)                                            | Your own infrastructure (not a hyperscaler) | WisdomAI's cloud  |
| Who operates it                | Shared (WisdomAI operates the platform; you govern provisioning of cloud resources) | You                                         | WisdomAI          |
| Object store & Postgres        | Cloud provider managed primitives                                                   | You provide your own                        | WisdomAI-provided |
| BYO Identity Provider          | ✓                                                                                   | ✓                                           | ✓                 |
| BYO LLM                        | ✓                                                                                   | ✓                                           | ✓                 |
| Data stays in your environment | ✓                                                                                   | ✓                                           | —                 |
| Setup complexity               | Medium                                                                              | High                                        | Low               |

## FAQs

The following questions cover common concerns about data handling across WisdomAI's deployment models.

<AccordionGroup>
  <Accordion title="Is the data encrypted in transit?">
    Yes, across all three deployment models. WisdomAI uses AES-256 at rest and TLS 1.2+ in transit.
  </Accordion>

  <Accordion title="Customer On-Prem: Is there any data stored outside the customer environment?">
    No. For Customer On-Prem deployments, nothing is stored outside of the customer environment. The WisdomAI Customer Success team works jointly with the customer application admin to help set up the WisdomAI SDK and the embeddings database (for RAG) metadata.
  </Accordion>

  <Accordion title="How long is personal data stored?">
    WisdomAI does not store any personal data, across any of its deployment models. The WisdomAI Platform connects to the customer's data warehouse via native and third-party integrations, and uses functionality provided by OpenAI and Anthropic to convert natural language into database queries and generate business intelligence from the data returned. Zero Data Retention (ZDR) agreements are in place with OpenAI and Anthropic. The customer can also choose to provide their own API key and host the WisdomAI Platform as a private SaaS instance within their environment.
  </Accordion>
</AccordionGroup>

## Related articles

<CardGroup>
  <Card title="iframe" icon="window" href="/integrations/embeddings/embedding-modes">
    Integrate WisdomAI using the iframe embedding path.
  </Card>

  <Card title="SDK" icon="code" href="/integrations/embeddings/sdk/sdk-overview">
    Use the React SDK for a native component approach.
  </Card>
</CardGroup>


# Provide Feedback to the System
Source: https://docs.wisdom.ai/explorers-feedback/provide-feedback-to-the-system



Your feedback is essential for improving WisdomAI's accuracy and reliability. By rating answers and providing corrections, you help the system learn and refine its responses. This guide walks you through the feedback process for all users.

* [Rate an Answer](#1-rate-an-answer)
* [Provide a Correction](#2-provide-a-correction)
* [Refine Your Question](#3-refine-your-question)

## 1. Rate an answer

After WisdomAI provides an answer, you will see thumbs-up (👍) and thumbs-down (👎) icons.

* **Click Thumbs Up (👍):** Use this if the answer is accurate, relevant, and helpful. This positive reinforcement helps the system understand what a good response looks like.
* **Click Thumbs Down (👎):** Use this if the answer is incorrect, incomplete, or unhelpful. This flags the response for review.

## 2. Provide a correction

When you click **Thumbs Down (👎)**, you will be prompted to provide more details. This is the most direct way to teach the system.

* **If the answer was incorrect:** Provide the correct answer in the text field.
* **If the answer was incomplete:** Add the missing context or information.

<img alt="Image showing the Thumb Down action in chat" title="Thumb Downv2 Pn" />

<Note>
  Currently, feedback icons (thumbs-up and thumbs-down) appear only for responses containing charts or structured data. Feedback for text-only responses is not yet supported, but will be available in a future update.
</Note>

## 3. Refine your question

You can also provide feedback by rephrasing your original question. If an initial query does not provide the desired result, refining it with more specific details helps WisdomAI learn to interpret your intent more accurately.

## Next steps

<CardGroup>
  <Card title="Connect and Test Tutorial" icon="rocket" href="/setting-up-wisdom-ai/basic-tutorial-connect-and-test">
    Walk through the initial setup to connect a data source and run your first query.
  </Card>

  <Card title="Validate and Test Answers" icon="book-open" href="/improve-wisdom-ai-responses/validate-and-test-answers">
    Test and validate both natural language responses and SQL query results directly within the chat interface.
  </Card>
</CardGroup>


# Chat with a Dashboard
Source: https://docs.wisdom.ai/explorers/chat-dashboard



Chat with a Dashboard embeds a conversational AI copilot directly into dashboard pages. You can ask natural-language questions about your dashboard data, get AI-generated executive summaries, see what changed since your last visit, and add new widgets to the dashboard, all without leaving the page.

## Before you start

To use this feature, make sure you have a dashboard to chat with. If you haven't created one yet, see [Turn Answers into Dashboards](/using-wisdom-ai-everyday/turn-answers-into-dashboards) or [Build Dashboards](/improve-wisdom-ai-responses/build-dashboards).

## Ask a question about your dashboard data

When you open a dashboard, the chat sidebar opens on the right side of the page, and two AI-generated tiles appear at the top:

* **Executive Summary**: A streaming narrative summary of all data in the current dashboard.

  <Tip>
    The Executive Summary can be customized to focus on the metrics and dimensions most relevant to you and your team. Use the customization options on the tile to tailor the narrative to your audience.

    <Frame>
      <img alt="Executive Summary tile  customization options" />
    </Frame>
  </Tip>
* **With changes since**: A comparison highlighting differences since your last visit or a specific date. You can select what suits you best.
  <Frame>
    <img alt="Executive Summary tile  customization options" />
  </Frame>

These tiles load automatically. No action is required to generate them.

<Frame>
  <img alt="dashboard-tiles" />
</Frame>

To start a chat with a dashboard:

1. Click **Dashboards** on the sidebar.
2. Select the dashboard you want to chat with.
   <Frame>
     <img alt="select-dashboard-image" />
   </Frame>
3. Click the chat input at the bottom of the sidebar and type a natural-language question about the data shown on the dashboard.
4. Press **Enter** or click the send button.
   <Frame>
     <img alt="dashboard-input" />
   </Frame>

The AI agent responds with data, tables, or charts scoped to the dashboard's domain.

<Frame>
  <img alt="Chat with a question typed in, and an AI response" />
</Frame>

## Add tiles to the dashboard

You can add new tiles to the dashboard directly from a chat response. Three tile types are available:

* **Visualization**: Wisdom queries your connected data source and returns an answer to your input. You can review the result, and once you're happy, click **Add latest visualization as a Tile** to lock it onto your dashboard. From then on, that metric is always visible without having to ask the question again.
  <Frame>
    <img alt="tile-visualization" />
  </Frame>
* **SQL query**: A tile that runs a custom SQL query directly against your data source. When you add a SQL tile, WisdomAI automatically generates the query based on your question. You can review and edit the query in the built-in SQL editor, give the tile a title, then click **Execute SQL** to preview the result. Once confirmed, click Add as Tile to pin it to your dashboard.
* **Summary**: A narrative text tile generated by WisdomAI that interprets and explains your dashboard data. When you add a summary tile, you can give it a title, write custom instructions to guide the format and focus of the summary.
  <Frame>
    <img alt="tile-summary" />
  </Frame>

## Next steps

<CardGroup>
  <Card title="Schedule Dashboard Notifications" icon="calendar-days" href="/using-wisdom-ai-everyday/schedule-dashboards-notifications">
    Set up automated notifications to keep stakeholders updated with the latest dashboard insights.
  </Card>

  <Card title="Share Dashboards and Set Access Control" icon="share-nodes" href="/using-wisdom-ai-everyday/share-dashboards-and-set-access-control">
    Learn how to share your dashboards with others and manage who can view or edit them.
  </Card>
</CardGroup>


# Getting Started for Explorers
Source: https://docs.wisdom.ai/explorers/getting-started-explorers



Welcome to WisdomAI. As an Explorer, you are the engine of data-driven decision-making. Your role is to transform raw data into meaningful business reports by asking questions in plain English, analyzing trends, and sharing those insights with your team.

This guide will help you navigate the platform and start uncovering insights in minutes.

## Power your analysis

Whether you need a quick answer or a deep dive, WisdomAI scales with you. You can easily query your data, fine-tune the logic for precision using SQL, and build insightful dashboards to share with your team:

<CardGroup>
  <Card icon="messages-question" title="Ask Questions">
    Query your data using natural-language, just like you're talking to a colleague.
  </Card>

  <Card icon="arrow-trend-up" title="Build Dashboards">
    Compile findings into dynamic, narrative-driven reports.
  </Card>

  <Card icon="paper-plane" title="Share Insights">
    Export or email your findings to keep your stakeholders informed.
  </Card>
</CardGroup>

## Get started in 3 steps

Follow this path to go from your first login to expert analysis.

<Steps>
  <Step icon="magnifying-glass" title="Ask your first question">
    Navigate to **New Chat** in the left sidebar. Type a specific question about your business, such as:

    > "What was our total revenue by region last quarter?"

    For complex queries, you can use [**Deep Analysis**](/advanced-features/deep-analysis). Simply propose your question, and the AI will outline an investigation plan for you. Once you confirm it, WisdomAI carries it out in the same chat window.
  </Step>

  <Step icon="filter" title="Refine and filter">
    Once WisdomAI provides an answer, use the **Filters** option to narrow your focus. You can filter by dates, specific table data, or product categories to get the exact data you need.
  </Step>

  <Step icon="book-open" title="Turn answers into dashboards">
    Don't let your answers sit in the chat. Use the **Add to Dashboard** feature to combine multiple visualizations and your own commentary into a shareable report.
  </Step>
</Steps>

## Essential guides for Explorers

Master the platform by exploring these detailed resources.

<CardGroup>
  <Card icon="message-question" href="/using-wisdom-ai-everyday/ask-better-questions" title="Ask Better Questions">
    Learn how to phrase queries using specific terms and timeframes for the most accurate results.
  </Card>

  <Card icon="chart-column" href="/using-wisdom-ai-everyday/turn-answers-into-dashboards" title="Turn Answers into Dashboards">
    Master the art of building interactive reports and diagrams to communicate insights.
  </Card>

  <Card icon="thumbs-up" href="/explorers-feedback/provide-feedback-to-the-system" title="Provide Feedback">
    Help WisdomAI learn your company's unique terminology and logic by rating responses.
  </Card>

  <Card icon="file-csv" href="/improve-wisdom-ai-responses/attach-files-to-chat" title="Use File Attachments in Chat">
    Understand how to integrate and analyze your own data stored in CSV, TSV, or Excel formats.
  </Card>
</CardGroup>


# Connect via AWS VPC Peering
Source: https://docs.wisdom.ai/getting-started/connect-data-sources/connect-aws-vpc-peering



This method establishes a private, secure connection between WisdomAI's AWS environment and your Amazon VPC. This process is managed with the help of the WisdomAI support team.

<Warning>
  VPC Peering cannot be configured directly in the UI. You must contact the WisdomAI support team to initiate this process.
</Warning>

## Prerequisites

Before you begin, ensure you have the following:

* An active WisdomAI account.
* A supported data source (e.g., Redshift, Databricks) that is already deployed and running within an AWS VPC.
* Access to an AWS IAM user or role with permissions to manage your VPC. Specifically, you will need to be able to:
  * View VPC details (like VPC ID and CIDR blocks).
  * Accept VPC peering requests.
  * Modify VPC route tables and security groups.

## Supported data sources

This connection method is applicable to any supported data source you have deployed within an AWS VPC, including but not limited to:

* Amazon Redshift
* Databricks (when deployed on AWS)
* ClickHouse (when deployed on AWS)

## Configuration steps

1. Collect the following details from your AWS account:
   * AWS Account ID and Region of the VPC
   * VPC ID
   * VPC CIDR block(s) (both primary and any secondary)
2. Email the information gathered in the previous step to the WisdomAI support team at `support@askwisdom.ai` to request a VPC peering connection.
3. The WisdomAI team will initiate a VPC peering request. You will receive an email with the request details and instructions to accept it within your AWS Management Console.
4. After accepting the request, you must update your VPC's route tables to direct traffic destined for the WisdomAI VPC through the peering connection. You also need to configure your security group rules to allow inbound traffic from WisdomAI's VPC CIDR. The support team will provide all necessary information for these steps.

## Next steps

<CardGroup>
  <Card title="Connect to Amazon Redshift" icon="aws" href="/getting-started/connect-data-sources/connect-to-amazon-redshift">
    Connect to Amazon Redshift using three methods: Direct Connection, SSH Tunnel, or VPC Peering, according to your network architecture.
  </Card>

  <Card title="Connect to Databricks" icon="layer-group" href="/getting-started/connect-data-sources/connect-to-databricks">
    Connect to Databricks using a Client ID and Client Secret for authentication, enabling secure and controlled access to your data.
  </Card>

  <Card title="Connect to Google BigQuery" icon="google" href="/getting-started/connect-data-sources/connect-to-google-bigquery">
    Connect to Google BigQuery using a Google Cloud Platform Service Account for secure and granular access to your data.
  </Card>
</CardGroup>


# Connect to an MCP Server
Source: https://docs.wisdom.ai/getting-started/connect-data-sources/connect-mcp-server



WisdomAI allows you to connect to any server that implements the [Model Knowledge Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro). This integration enables WisdomAI to scan metadata, build a knowledge graph, and fetch real-time data to generate visualizations when users ask natural-language questions.

## Prerequisites

* [Admin access](/manage-account/access-management) to your WisdomAI Organization.
* The Server URL (for HTTP/SSE) or Command (for STDIO) of your MCP server.
* Authentication credentials (API Key or OAuth configuration), if required by your server.

## Connect an MCP Server

Follow these steps to register your MCP server as a data source in WisdomAI.

1. Navigate to **Connections** > **Add Connection**.
2. In the **Data source** dropdown, select **MCP Server**.
3. Enter a unique **Connection name** (e.g., "Linear MCP Server").
4. Select the **Transport Type** supported by your server:
   * **Streamable HTTP**: Uses standard HTTP streaming for communication.
   * **SSE**: Uses Server-Sent Events.
   * **STDIO**: Runs the server as a local process via standard input/output.
5. Enter the **Server URL** (for HTTP/SSE) or connection details.
6. Select the **Authentication Type**:
   * **None**: For public or internal servers without auth.
   * **API Key**: Uses a static key for all requests.
   * **OAuth**: Uses user-based authentication.
7. (Optional) Click **+ Add Header** to include custom headers required by your environment.
   <img alt="Mcp 01" title="Mcp 01" />
   <img alt="Mcp 01" title="Mcp 01" />
8. Click **Connect**. You may be prompted to authorize the connection to validate the setup.

<img alt="Chat interface prompting the user to authenticate with the MCP tool" />

<img alt="Chat interface prompting the user to authenticate with the MCP tool" />

<Info>
  **User-based authentication**

  If you select **OAuth**, authentication happens on a user-by-user basis. WisdomAI does not store a global credential. Instead, when a user asks a question that requires data from this server, WisdomAI will prompt them to authenticate via a secure pop-up during the chat session.
</Info>

## Validate the connection

Once connected, you can verify the integration by asking a natural language question in the chat interface.

1. Start a **Chat**.
2. Ask a question relevant to the connected tool (e.g., "Show me my issues").
3. If using OAuth, and you haven't authenticated yet, WisdomAI will detect the need for authentication. Click **Connect** in the chat response and Authorize the request in the pop-up window. \
   WisdomAI will pull the requested data and generate the appropriate visualization or text response.

<img alt="Mcp 02" />

<img alt="Mcp 02" />

## Next steps

<CardGroup>
  <Card title="Connect to Databricks" icon="layer-group" href="/getting-started/connect-data-sources/connect-to-databricks">
    Connect to Databricks using a Client ID and Client Secret for authentication, enabling secure and controlled access to your data.
  </Card>

  <Card title="Connect to Google BigQuery" icon="google" href="/getting-started/connect-data-sources/connect-to-google-bigquery">
    Connect to Google BigQuery using a Google Cloud Platform Service Account for secure and granular access to your data.
  </Card>

  <Card title="Connect to Amazon Redshift" icon="aws" href="/getting-started/connect-data-sources/connect-to-amazon-redshift">
    Connect to Amazon Redshift using three methods: Direct Connection, SSH Tunnel, or VPC Peering, according to your network architecture.
  </Card>
</CardGroup>


# Connect to Amazon Redshift
Source: https://docs.wisdom.ai/getting-started/connect-data-sources/connect-to-amazon-redshift



WisdomAI allows you to connect to Amazon Redshift by choosing one of three methods:

1. [Direct Connection](#option-1-direct-connection)
2. [Connect via an SSH Tunnel](#option-2-connect-via-an-ssh-tunnel)
3. [Connect via VPC Peering](#option-3-connect-via-vpc-peering)

This flexibility ensures you can establish a secure connection that matches your specific network architecture.

## Prerequisites

Before you begin, make sure you have the following:

* Your Amazon Redshift cluster endpoint, port, database name, and user credentials.
* Network access that allows WisdomAI to connect to your Redshift cluster. This may require configuring your firewall or AWS security groups.
* If using an SSH tunnel, you need the credentials for your bastion host.
* If using VPC peering, you need permissions to manage VPC settings in your AWS account.

## Option 1: Direct connection

Use this method if your Redshift cluster is publicly accessible or if you have allowlisted WisdomAI's CIDR blocks (`35.238.115.103/32` and `34.82.248.105/32`) in your security group.

1. In WisdomAl, navigate to the **Connections** section and click **Add Connection**.
2. Select **Redshift** as the data source type.
3. Fill in the connection details in the **Redshift connection details** section:

| Requirement      | Description                                      |
| :--------------- | :----------------------------------------------- |
| Host             | Redshift cluster endpoint                        |
| Port             | Typically `5439`                                 |
| Username         | Database user with read access                   |
| Password         | User password                                    |
| Database Filters | Optionally restrict which databases are crawled. |

4. Click **Save and Sync metadata.** WisdomAl will use the provided credentials to connect to your Redshift account and scan the metadata of the specified databases and tables.

<img alt="Snippet displaying the Add Connection page" />

<img alt="Snippet displaying the Add Connection page" />

<img alt="Snippet displaying the Add Connection page" />

## Option 2: Connect via an SSH tunnel

Use this method to securely connect to a Redshift cluster that is not publicly accessible by routing traffic through a bastion host.

1. On the **Add Connection** page, fill in the direct connection details and expand the **SSH Tunnel Configuration** section.
2. Complete the **SSH Tunnel configuration fields**.

| Requirement              | Description                                                   |
| :----------------------- | :------------------------------------------------------------ |
| SSH Host                 | Hostname or IP address of the bastion host                    |
| SSH Port                 | Port number on the SSH host (e.g., `22`)                      |
| SSH Username             | The username required to log in to the bastion host           |
| Authentication Method    | Authenticate using either a **Private Key** or a **Password** |
| SSH Private Key/Password | The Private Key or Password for the SSH authentication        |

3. Click **Save and Sync metadata.**

<img alt="Snippet displaying the Add Connection page with the SSH Tunnel Configuration section displayed" />

<img alt="Snippet displaying the Add Connection page with the SSH Tunnel Configuration section displayed" />

## Option 3: Connect via VPC peering

This method establishes a private and secure network connection between WisdomAI's AWS environment and your Amazon VPC, preventing exposure to the public internet.

This is a standardized procedure for all supported data sources hosted on AWS. For the complete, step-by-step instructions, please refer to our comprehensive guide: [Connect via AWS VPC Peering](/getting-started/connect-data-sources/connect-aws-vpc-peering).

## Next steps

<CardGroup>
  <Card title="Connect to Databricks" icon="layer-group" href="/getting-started/connect-data-sources/connect-to-databricks">
    Connect to Databricks using a Client ID and Client Secret for authentication, enabling secure and controlled access to your data.
  </Card>

  <Card title="Connect to Google BigQuery" icon="google" href="/getting-started/connect-data-sources/connect-to-google-bigquery">
    Connect to Google BigQuery using a Google Cloud Platform Service Account for secure and granular access to your data.
  </Card>

  <Card title="Connect and Test Tutorial" icon="rocket" href="/setting-up-wisdom-ai/basic-tutorial-connect-and-test">
    Walk through the initial setup to connect a data source and run your first query.
  </Card>
</CardGroup>


# Connect to Databricks
Source: https://docs.wisdom.ai/getting-started/connect-data-sources/connect-to-databricks



WisdomAI connects to Databricks using a **Client ID** and **Client Secret** for authentication. This method ensures secure and granular control over the data WisdomAI can access.

## Prerequisites

Before you begin, make sure you have the following:

* An active Databricks workspace.
* Permissions to create and manage **Service Principals** within your Databricks account or workspace.
* A Databricks **SQL Warehouse** set up and running.

## 1. Obtain Databricks connection details

You will need the following four pieces of information from your Databricks environment:

1. **Host**: The URL of your Databricks workspace, which typically looks like `https://<region>.cloud.databricks.com/`. You can find this in your SQL Warehouse connection details.
2. **HTTP Path**: The specific path to your SQL Warehouse, usually starting with `/sql/1.0/warehouses/`. You can find this in the "Connection Details" tab of your SQL Warehouse.
3. **Client ID**: The Application ID of your Databricks Service Principal.
4. **Client Secret**: The secret key generated for your Databricks Service Principal.

### How to find your connection details

Follow these steps to find the necessary credentials.

#### Host and HTTP path

1. Navigate to your Databricks Workspace.
2. Go to **SQL Warehouses** (or SQL Endpoints).
3. Select the warehouse you want to connect to.
4. Click on the **Connection Details** tab. Here you will find the **Server Hostname** (your Host) and the **HTTP Path**.

#### Client ID and client secret (using a Databricks-managed Service Principal)

You'll first need to create a Service Principal in Databricks.

**Step 1: Create a Service Principal**

1. Log in to your Databricks environment.
   * **A) account-level permissions:** Log in to your Databricks **account console**.
   * **B) administrator-level permissions:** Log in to your Databricks **workspace** as an administrator.
2. Navigate to the Service Principals section.
   * **A) From Account Console:** Navigate to **User management > Service principals**.
   * **B) From Workspace:** Navigate to **Admin Settings** (click your username in the top right, then Admin Settings) > **Identity and access > Service principals**.
3. Click **Add service principal**.
4. Select **Databricks managed**.
5. Provide a descriptive **Name** for the service principal (e.g., WisdomAI-ServicePrincipal).
6. Click **Add service principal**.
7. Once created, you will see the **Application ID** for this service principal. This is your **Client ID**. Copy this value.

**Step 2: Generate a Client Secret for the Service Principal**

1. From the service principal's page, go to the **Secrets** tab.
2. Under OAuth secrets, click **Generate secret**.
3. Set a lifetime for the secret (up to 730 days) and click **Generate**.
   <Note>
     Choose an expiration that balances security and operational convenience.
   </Note>
4. Immediately copy the displayed secret. This is your **Client Secret**.

<Warning>
  The Client Secret is only shown once and cannot be retrieved later. Please store it in a secure location immediately.
</Warning>

## 2. Assign permissions in Databricks

The Service Principal needs specific permissions to access the required data that WisdomAI needs.

* **SQL Warehouse/Cluster Permissions**: Grant **CAN USE** permission to the Service Principal on the SQL Warehouse you are connecting to. You can do this from the **Permissions** tab of the SQL Warehouse.
* **Data Privileges**: The service principal requires the following privileges in Unity Catalog (or Hive Metastore):
  * `USE CATALOG` on the target catalog.
  * `USE SCHEMA` on the target schema.
  * `SELECT` on the tables and views you want WisdomAI to access.

You can grant these permissions using SQL commands. Here are some examples:

```sql theme={null}
-- Grant permission to use a specific catalog
GRANT USAGE ON CATALOG <your_catalog_name> TO `<service_principal_id>`;

-- Grant permission to use a specific schema
GRANT USAGE ON SCHEMA <your_catalog_name>.<your_schema_name> TO `<service_principal_id>`;

-- Grant select permission on table
GRANT SELECT ON TABLE <your_catalog_name>.<your_schema_name>.<your_table_name> TO `<service_principal_id>`;

-- Grant select permission on all tables in a schema
GRANT SELECT ON SCHEMA <your_catalog_name>.<your_schema_name> TO `<service_principal_id>`;
```

Replace `<service_principal_id>` with the Application ID of your service principal, and `<your_catalog_name>`,`<your_schema_name>`, and `<your_table_name>` with your specific values.

## 3. Connect WisdomAI to Databricks

Once you have gathered the required information, you can configure the connection in WisdomAI:

1. In WisdomAI, navigate to the **Connections** section and click **Add Connection**.
2. Select **Databricks** as the data source type.
3. Fill in the connection details in the "Databricks connection details" section.
   * **Connection Name**: Choose a descriptive name for your connection (e.g., "Databricks Prod").
   * **Host**: Paste the Server Hostname you obtained from Databricks.
   * **HTTP Path**: Paste the HTTP Path for your SQL Warehouse.
   * **Client ID**: Enter your Client ID (Application ID). This field is mandatory.
   * **Client Secret**: Enter your Client Secret (the value copied immediately after creation). This field is mandatory.
   * **Catalog Filters (Optional)**: Specify any Catalog Filters if you want to further restrict the catalogs/schemas WisdomAI crawls.
4. Click **Save and Sync metadata**. WisdomAI will use the provided credentials to connect to Databricks and scan the metadata of the specified catalogs and tables.

<img alt="image.png" />

<img alt="image.png" />

## Security considerations and best practices

* **Least Privilege**: Always follow the principle of least privilege. Only grant the necessary permissions to the Service Principal.
* **Secure Key Management**: Treat your Client ID and Client Secret like passwords. Avoid sharing them via insecure channels, such as unencrypted email. Use secure methods, such as LastPass or other secure file-sharing services.
* **Credential Rotation**: Regularly rotate your Client Secrets to enhance security, especially before their expiration.

## Troubleshooting common issues

Having trouble? Here are solutions to some frequently encountered problems.

### Authentication failed or invalid credentials

* Ensure the Host, HTTP Path, Client ID, and Client Secret are complete and correct. No extra characters, spaces, or missing lines.
* Verify that the Client Secret has not expired or been revoked in Databricks.
* Confirm that the Service Principal exists and is enabled in Databricks.

### Permission denied errors

* Double-check that the Service Principal has the necessary `CAN USE` permission on the SQL Warehouse.
* Verify that the Service Principal has the correct `USE CATALOG`, `USE SCHEMA`, and `SELECT` privileges on the Databricks catalogs, schemas, and tables you are trying to access.
* Confirm that the SQL Warehouse is running and accessible.

### Catalog not found or table not found

* Verify the spelling of the catalog or table names.
* If using catalog filters in WisdomAl, ensure the catalog is included in the filter.
* Confirm that the Service Principal has permissions on the specific catalog you are trying to access.

### Connection timeout or network errors

* Verify that WisdomAI's CIDR blocks (`35.238.115.103/32` and `34.82.248.105/32`) are allowlisted in your Databricks network policies or any corporate firewalls.

## Next steps

<CardGroup>
  <Card title="Connect to Snowflake" icon="snowflake" href="/getting-started/connect-data-sources/connect-to-snowflake">
    Connect to Snowflake directly or via a proxy using key-pair authentication and a Snowflake virtual warehouse.
  </Card>

  <Card title="Connect to Google BigQuery" icon="google" href="/getting-started/connect-data-sources/connect-to-google-bigquery">
    Connect to Google BigQuery using a Google Cloud Platform Service Account for secure and granular access to your data.
  </Card>

  <Card title="Connect and Test Tutorial" icon="rocket" href="/setting-up-wisdom-ai/basic-tutorial-connect-and-test">
    Walk through the initial setup to connect a data source and run your first query.
  </Card>
</CardGroup>


# Connect to Google BigQuery
Source: https://docs.wisdom.ai/getting-started/connect-data-sources/connect-to-google-bigquery



WisdomAI connects to Google BigQuery using a service account for background operations such as metadata crawling. To run end-user queries, you can either continue using that same service account or enable Google OAuth so each user authenticates with their own Google account for finer-grained access control and per-user audit trails.

## Prerequisites

* A GCP service account created with the required BigQuery roles. See [Set up a GCP service account for WisdomAI](/getting-started/connect-data-sources/set-up-gcp-service-account).
* The JSON key file for that service account, downloaded to your computer.
* Your Google Cloud project ID, available on the GCP Console dashboard.

## Create the connection

These steps create the connection in WisdomAI and authenticate the service account. Complete them whether you plan to use service account authentication only or enable OAuth on top.

1. In WisdomAI, go to **Connections** and click **Add Connection**.
2. Select **BigQuery** as the data source type.

<Frame>
  <img alt="Add Connection screen showing BigQuery selected as the data source type" title="Add Connection BigQuery" />
</Frame>

3. Enter a **Connection name**, for example `BigQuery Prod`.
4. Under **Account Information**, paste the contents of your service account JSON into **Service Account Info JSON**.
   <Note>
     This field is required for crawling and metadata discovery.
   </Note>
5. (**Optional**) Enter **Authorization scopes** to restrict the OAuth permission scopes granted to the connection.
6. (**Optional**) Enter a **Billing Project ID** to specify which project to bill for queries. Leave this field empty to use your service account's default project.
7. Under **Projects**, configure at least one BigQuery project:
   * In the **Project 1** card, enter your Google Cloud **Project ID**.
   * (**Optional**) Enter **Dataset filters** to restrict which datasets WisdomAI crawls for that project.
   * To connect additional projects, click **+ Add Project** and repeat these sub-steps for each one.

<Frame>
  <img alt="Connection Details" title="Connection Details" />
</Frame>

At this point, you have two options:

* To use the service account for all queries, click **Save and Sync metadata**. WisdomAI connects to BigQuery, scans metadata for the specified datasets and tables, and your connection is ready.
* To authenticate end-user queries with individual Google accounts, leave the form open and continue to the next section before saving.

## Enable OAuth for user queries

OAuth lets each WisdomAI user run BigQuery queries under their own Google identity. The service account still handles crawl jobs and metadata discovery in the background.

<Note>
  Enabling OAuth requires you to work across two systems. You will create an OAuth client in the Google Cloud Console, then return to WisdomAI to paste the credentials and authenticate.
</Note>

### Start the OAuth setup in WisdomAI

Begin in the connection form you already filled out in the previous section.

1. Select **Enable OAuth for user queries (optional)**. The **Google OAuth Client ID** and **Google OAuth Client Secret** fields appear.
2. Leave the form open. You will return here after creating the OAuth client in Google Cloud.

<Frame>
  <img alt="Enable OAuth for user queries checkbox" title="Oauth Enabled Single" />
</Frame>

### Create an OAuth client in Google Cloud

The OAuth client lets WisdomAI request access tokens on behalf of your users.

1. In the Google Cloud Console, open the **Google Auth Platform**.
2. Go to **Clients** and access **Create OAuth client ID**.
3. Set **Application type** to **Web application**.
4. Enter a **name** for the client, for example `WisdomAI`.
5. Leave **Authorized JavaScript origins** empty.
6. Under **Authorized redirect URIs**, add:
   ```text theme={null}
   https://api.descope.com/v1/outbound/oauth/callback
   ```
7. Click **Create**.

<Frame>
  <img alt="Google Cloud Console OAuth client creation" />
</Frame>

8. Google Cloud displays a confirmation dialog with the new credentials. Copy the **Client ID** and **Client Secret**, and optionally click **Download JSON** to save them locally for reference.

<Frame>
  <img alt="Oauth Step8" />
</Frame>

### Authenticate in WisdomAI

Return to the WisdomAI connection form to finish the OAuth setup.

1. Paste the **Client ID** and **Client Secret** into the corresponding fields.
2. Click **Connect with Google**.
3. In the Google sign-in popup, select the Google account you want to use for authentication.

<Frame>
  <img alt="O Auth Signin Google Account" title="O Auth Signin Google Account" />
</Frame>

4. After successful authentication, you are redirected back to WisdomAI. Verify that the OAuth connection status shows as connected.
5. Click **Save** to complete the connection setup.

## Security considerations

Follow these practices to keep your BigQuery connection secure:

* **Least privilege.** Grant only the roles WisdomAI needs. If dataset-level access is sufficient, avoid assigning project-level roles.
* **Secure key management.** Treat the service account JSON key like a password. Store it in a secrets manager and share it only through secure channels such as a password manager.
* **OAuth for audit trails.** When you need per-user accountability for query activity, enable OAuth so each query runs under an individual Google identity.

## Troubleshooting

Common issues you might run into when setting up the connection.

<AccordionGroup>
  <Accordion title="Authentication failed or invalid credentials">
    * Confirm the JSON key you pasted is complete, with no missing lines or extra characters.
    * Verify that the `project_id` value in the JSON key matches the project ID you entered in the connection form.
  </Accordion>

  <Accordion title="Permission denied errors">
    * Check that the service account has all three required roles: **BigQuery Data Viewer**, **BigQuery Job User**, and **BigQuery Read Session User**.
    * Confirm those roles are assigned at the right level — either project-wide, or on every dataset WisdomAI needs to read.
    * Confirm the BigQuery API is enabled in your Google Cloud project.
  </Accordion>

  <Accordion title="Dataset or table not found">
    * Verify the spelling of the dataset and table names.
    * If you set **Dataset Filters** in the connection, confirm the dataset is included in the filter.
    * Confirm the service account has access to the specific dataset you are querying.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="Connect to Snowflake" icon="snowflake" href="/getting-started/connect-data-sources/connect-to-snowflake">
    Connect to Snowflake directly or via a proxy using key-pair authentication and a Snowflake virtual warehouse.
  </Card>

  <Card title="Connect to an MCP Server" icon="server" href="/getting-started/connect-data-sources/connect-mcp-server">
    Connect WisdomAI to any server implementing the Model Context Protocol (MCP) to scan metadata, build a knowledge graph, and retrieve real-time data for natural language queries.
  </Card>

  <Card title="Connect and Test Tutorial" icon="rocket" href="/setting-up-wisdom-ai/basic-tutorial-connect-and-test">
    Walk through the initial setup to connect a data source and run your first query.
  </Card>
</CardGroup>


# SharePoint
Source: https://docs.wisdom.ai/getting-started/connect-data-sources/connect-to-sharepoint



WisdomAI supports connecting to Microsoft SharePoint as an unstructured data source. The SharePoint connector crawls files from your SharePoint sites and enables multi-site ingestion of diverse file formats, including PDFs, spreadsheets, and images, while providing granular filtering to ensure that only new or modified content is processed after the initial crawl.

## Get started

Before you begin, ensure you have the following:

* **SharePoint Online:** The connector works with SharePoint Online (part of Microsoft 365). On-premises SharePoint Server is not supported.
* **SharePoint Site URLs:** The full URLs of the sites you want to connect (e.g., `https://contoso.sharepoint.com/sites/teamsite`).
* **Azure AD permissions**: The connector requires the following Microsoft Graph API application permissions granted on your Azure AD tenant:
  * `Sites.Read.All`: Read items in all site collections.
  * `Files.Read.All`: Read all files that the app has access to.
* **Authentication Methods:** You must have one of the authentication methods configured:
  * An Azure AD app registration with a client secret (Service Principal).
  * Your Azure AD Tenant ID for the WisdomAI-managed app (Dedicated Multitenant App).

## Authentication methods

Choose the authentication method that best fits your organization's security requirements.

<Tabs>
  <Tab title="Service Principal (Client Secret)">
    Use your own Azure AD app registration to authenticate. This gives you full control over the app and its permissions.

    1. In the [**Azure Portal**](https://portal.azure.com), navigate to **Azure Active Directory** > **App registrations** > **New registration**.
    2. Register a new application (e.g., "WisdomAI SharePoint Connector").
    3. Note the **Application (client) ID** and **Directory (tenant) ID** from the **Overview** page.
    4. Navigate to **Certificates & secrets** > **New client secret**.
    5. Create a secret and copy the **Value** immediately; it will not be shown again.
    6. Navigate to **API permissions** > **Add a permission** > **Microsoft Graph** > **Application permissions**.
    7. Add the following permissions:
       * `Sites.Read.All`
       * `Files.Read.All`
    8. Click **Grant admin consent** to approve the permissions for your tenant.

    You will need the following values when configuring the connection in WisdomAI:

    | Field         | Description                                            |
    | :------------ | :----------------------------------------------------- |
    | Client ID     | The Application (client) ID from your app registration |
    | Tenant ID     | The Directory (tenant) ID of your Azure AD tenant      |
    | Client Secret | The client secret value you generated                  |
  </Tab>

  <Tab title="Dedicated Multitenant App (WisdomAI Managed)">
    WisdomAI creates and manages the Azure AD app on your behalf. You only need to provide your Tenant ID and grant admin consent.

    1. Locate your **Azure AD Tenant ID** in the [Azure Portal](https://portal.azure.com) under **Azure Active Directory** > **Overview**.
    2. During the WisdomAI connection setup, enter your **Tenant ID**.
    3. Click **Grant Admin Consent** when prompted.
    4. A Microsoft consent dialog will open. You must approve the permissions (`Sites.Read.All` and `Files.Read.All`) for the WisdomAI-managed app.
    5. The status in WisdomAI will update to **Granted** once approved.

    <Note>
      Granting admin consent for these permissions requires a user with the **Global Administrator** or **Privileged Role Administrator** role in your Azure AD tenant.
    </Note>
  </Tab>
</Tabs>

***

## Setting up the connection

Follow these steps to establish the connection within WisdomAI:

1. Navigate to the **Overview** tab in your WisdomAI domain and click **Add Data Source**.
2. Select **Connect another source** from the **Add** **Data Source** selector and click **Add Data Source**.

<img alt="sharepoint-add-data" />

3. Select **Connect to Data store or MCP server**.
4. Enter a descriptive **Connection name** (e.g., "Marketing SharePoint") and select **SharePoint** as the data source.

<img alt="sharepoint-connect-source" />

5. **Configure Authentication:** Choose your preferred method (Service Principal or Dedicated Multitenant App) and enter the required credentials.
   <Frame>
     <img alt="Sharepoint Cd" />
   </Frame>
6. **Configure SharePoint Sites:**
   * Click **Add Site** and enter the full **Site URL** (e.g., `https://contoso.sharepoint.com/sites/teamsite`).
     <Note>
       You can add multiple sites to a single connection.
     </Note>
   * (Optional) Click **Add Library** to restrict crawling to specific document libraries. If left blank, all libraries on the site are crawled.
   * (Optional) Click **Add Path** to restrict crawling to specific folders within a library. Enter the path prefix (e.g., `Marketing/2024`) without a leading `/`.
7. Click **Save**. WisdomAI will validate the credentials before saving.

<img alt="sharepoint-sites" />

8. After the connection is created, add it as a data source to your domain. WisdomAI will begin crawling the configured SharePoint sites.

## Configuration reference

This section details the parameters used to define the scope of your data connection.

### Sites

Each connection can include one or more SharePoint sites. At least one site is required.

| Field                  | Required | Description                                                                                  |
| :--------------------- | :------- | :------------------------------------------------------------------------------------------- |
| **Site URL**           | Yes      | The full URL of the SharePoint site (e.g., `https://contoso.sharepoint.com/sites/teamsite`). |
| **Document Libraries** | No       | Optionally restrict which document libraries within the site are crawled.                    |

### Document libraries

Within each site, you can optionally specify which document libraries to crawl. If none are specified, all document libraries in the site are included.

| Field                   | Required | Description                                                       |
| :---------------------- | :------- | :---------------------------------------------------------------- |
| **Library Name**        | Yes      | The name of the document library (e.g., `Documents`).             |
| **Path Prefix Filters** | No       | Optionally restrict which folders within the library are crawled. |

### Path prefix filters

Within each document library, you can optionally specify folder path prefixes to scope the crawl. If none are specified, all files in the library are included.

* **Formatting:** Do **not** include a leading `/`. Use `Reports/Q1`, not `/Reports/Q1`.
* **Case-Sensitivity:** Filters are case-insensitive (e.g., `Marketing` matches `MARKETING`).
* **Matching:** Filters match on prefix. `Marketing` will match `Marketing/file.pdf` and `Marketing/2024/report.pdf`.
* **Multiple Filters:** You can add multiple filters per library. A file is included if it matches **any** configured filter.

**Example configuration**:

```txt theme={null}
Site: <https://contoso.sharepoint.com/sites/marketing>
  Library: Shared Documents
    Path Filter: Campaigns/2024
    Path Filter: Brand Guidelines
  Library: Reports
    (no path filters — all files in this library are crawled)
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication failed">
    * Verify that the **Client ID**, **Tenant ID**, and **Client Secret** are correct and have not expired.
    * For the Dedicated Multitenant App method, confirm that admin consent has been granted (the status should show "Granted" in WisdomAI).
  </Accordion>

  <Accordion title="Connection validates, but no files were crawled">
    * Confirm the Site URL is correct and accessible. Ensure the **Site URL** points to a specific site, not the root SharePoint domain.
    * Verify the **Library Name** matches the SharePoint library exactly.
    * If using path prefix filters, verify the paths exist and do not start with `/`.
    * Ensure the Azure AD app's permissions (`Sites.Read.All`, `Files.Read.All`) have been granted admin consent.
  </Accordion>

  <Accordion title="Specific inaccessible sites">
    * The app may authenticate successfully but lack access to certain sites. Verify that your Azure AD app permissions are tenant-wide (admin-consented), not scoped to specific sites only.
  </Accordion>

  <Accordion title="Admin consent cannot be granted">
    * The user granting consent must have the **Global Administrator** or **Privileged Role Administrator** role in Azure AD.
    * If your organization restricts app consent, contact your Azure AD administrator.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="Connect to GoogleSheets" icon="table" href="/integrations/google-sheets">
    Learn how to connect WisdomAI to GoogleSheets.
  </Card>

  <Card title="Connect to Slack" icon="slack" href="/integrations/connect-to-slack">
    Learn how to connect WisdomAI to Slack.
  </Card>
</CardGroup>


# Connect to Snowflake
Source: https://docs.wisdom.ai/getting-started/connect-data-sources/connect-to-snowflake



WisdomAl supports connecting to Snowflake directly or via a Proxy. This document outlines the process for direct connections.

## Prerequisites

Before connecting WisdomAl to Snowflake, be sure to have:

* An active Snowflake account and workspace.
* A Snowflake virtual warehouse with appropriate compute resources.
* A Snowflake user with the necessary permissions to create or assign roles and manage private keys.
* Network access configured to allow connections from WisdomAl to your Snowflake instance.

## 1. Information required for direct connection setup:

To connect WisdomAl to Snowflake directly, you will need the following information:

* **Account**: Your Snowflake account identifier. This consists of the name of the account prefixed by its organization (e.g., myorg-account123).
  <Note>
    Refer to [the Account identifiers page on the Snowflake documentation](https://docs.snowflake.com/en/user-guide/admin-account-identifier) for details on finding your account identifier.
  </Note>
* **Warehouse**: The name of the virtual warehouse to use for compute (e.g., "COMPUTE\_WH").
* **User**: The Snowflake username that WisdomAl will use for access.
* **Private Key**: The private key associated with the Snowflake user. Ensure the key is in PEM format, including the `----BEGIN...PRIVATE KEY` and `-END...PRIVATE KEY` headers and footers.
  <Note>
    Refer to the [Key-pair authentication page on the Snowflake documentation](https://docs.snowflake.com/en/user-guide/key-pair-auth) for details on generating a private key.
  </Note>
* **Private Key Passphrase**: This is required if your private key is encrypted.
* **Role**: The Snowflake role to use for access privileges (e.g., ACCOUNTADMIN). See the Using a Custom Role section below for details.
* **\[Optional] Database Filters**: See the Database Filters section below for more details.
* **\[Optional] Allowlist**: You may need to allowlist WisdomAI's CIDR blocks in your Snowflake network policies or firewalls to allow incoming connections: `35.238.115.103/32` and `34.82.248.105/32`.

## 2. Using a custom role:

To create a custom role and use it for WisdomAl communication, ensure the role has:

* USAGE privilege on the warehouse and on the required databases/schemas.
* SELECT privilege on all tables that you want to connect with WisdomAl.

Refer to the following SQL statements to grant appropriate privileges:

* `grant usage on warehouse <warehouse> to role <role>;`
* For each database:
  * `grant usage on database <database> to role <role>;`
  * `grant usage on all schemas in database <database> to role <role>;`
  * `grant select on all tables in database <database> to role <role>;`
* To grant access to all future schemas and tables added in this database:
  * `grant usage on future schemas in database <database> to role <role>;`
  * `grant select on future tables in database <database> to role <role>;`

<Note>
  See [this page of the Snowflake documentation](https://docs.snowflake.com/en/sql-reference/sql/grant-privilege) for more details on granting privileges to your role.
</Note>

## 3. Connect WisdomAI to Snowflake:

Once you have gathered the required information, you can configure the connection in WisdomAI:

1. In WisdomAl, navigate to the **Connections** section and click **Add Connection**.
2. Select **Snowflake** as the data source type.
3. Fill in the connection details in the **Snowflake connection details** section:
   * **Connection Name**: Choose a descriptive name for your connection (e.g., "Snowflake Prod").
   * **Account**: Enter your Snowflake account identifier (e.g., XMSPMYE-PAB51256).
   * **Warehouse**: Enter the name of your virtual warehouse (e.g., COMPUTE WH).
   * **User**: Enter the Snowflake username (e.g., user01).
   * **Private Key**: Paste the content of your private key, including the `BEGIN ENCRYPTED PRIVATE KEY` and `END PRIVATE KEY` headers and footers.
   * **Private Key Passphrase**: Enter the passphrase if your private key is encrypted.
   * **Role**: Enter the Snowflake role (e.g., ACCOUNTADMIN).
   * **Database Filters (Optional)**: Specify any Database Filters if you want to restrict the databases WisdomAl crawls further.
4. Click **Save and Sync metadata.** WisdomAl will use the provided credentials to connect to your Snowflake account and scan the metadata of the specified databases and tables.

<img alt="image.png" />

<img alt="image.png" />

## Security considerations and best practices

* **Least Privilege**: Always follow the principle of least privilege. Only grant the necessary permissions (USAGE, SELECT) to the Snowflake user that WisdomAl will use, and restrict it to specific warehouses, databases, and schemas.
* **Secure Credential Management**: Treat your private key file (rsa\_key.p8) as extremely sensitive. Store it in a secure, encrypted location (e.g., a secrets manager or secure file system). Never hardcode private keys in application code or share them via insecure channels.
* **Credential Rotation**: Regularly rotate private keys used for WisdomAl's Snowflake connection.
* **Auditing**: Enable and regularly review Snowflake audit logs to monitor access and activity performed by the WisdomAl connection.

## Troubleshooting common issues

Having trouble? Here are solutions to some frequently encountered problems.

### Authentication failed or invalid private key

* Ensure the private key content is copied exactly, including the `BEGIN` and `END` headers and footers, without any extra spaces or line breaks.
* If your private key is encrypted, verify that the Private Key Passphrase is entered correctly.
* Confirm that the Snowflake username matches the user associated with the private key.

### Warehouse not found or database not found

* Double-check the spelling of the warehouse and database names in the WisdomAl connection details.
* Ensure the Snowflake user/role has USAGE privilege on the specified warehouse and database.

### Insufficient privileges

* Verify that the Snowflake role assigned to WisdomAl has all the necessary USAGE and SELECT privileges as detailed in the Using a Custom Role section above.
* If you're using database filters, ensure the role has privileges on the filtered databases.

### Connection timeout or network errors

* Verify that WisdomAl's CIDR block (`35.238.115.103/32` and `34.82.248.105/32`) is allowlisted in your Snowflake network policies or any corporate firewalls.

## Next steps

<CardGroup>
  <Card title="Connect to Databricks" icon="layer-group" href="/getting-started/connect-data-sources/connect-to-databricks">
    Connect to Databricks using a Client ID and Client Secret for authentication, enabling secure and controlled access to your data.
  </Card>

  <Card title="Connect to an MCP Server" icon="server" href="/getting-started/connect-data-sources/connect-mcp-server">
    Connect WisdomAI to any server implementing the Model Context Protocol (MCP) to scan metadata, build a knowledge graph, and retrieve real-time data for natural language queries.
  </Card>

  <Card title="Connect and Test Tutorial" icon="rocket" href="/setting-up-wisdom-ai/basic-tutorial-connect-and-test">
    Walk through the initial setup to connect a data source and run your first query.
  </Card>
</CardGroup>


# Search the Web
Source: https://docs.wisdom.ai/getting-started/connect-data-sources/search-the-web



WisdomAI can search the internet and fetch content from public web pages when answering user questions. When enabled on a domain, the AI automatically supplements its database-driven analysis with real-time information from the web, such as industry benchmarks, market trends, competitor data, or publicly available reference material.

## Prerequisites

* [Admin access](/manage-account/access-management) to your WisdomAI Organization.
* An existing [Domain](/setting-up-wisdom-ai/manage-domains/understand-domains) to enable Web Search on.

## 1. Enable web search on a Domain

You can enable Web Search when creating a new domain or by adding it as a data source to an existing domain.

### Add web search to an existing Domain

1. Navigate to your **Domain** and open the **Overview** tab.
2. Click **Add Data Source**.
3. In the data source picker, select **Web Search**.
4. Click **Submit**. A confirmation message will appear indicating that Web Search has been enabled.

<Frame>
  <img alt="Image" />
</Frame>

### Enable web search during Domain creation

1. Navigate to **Domains** and click **Add Domain**.
2. Enter a **Domain name**.
3. In the data source selection, choose **Web Search**.
4. Complete the domain creation process.

Once enabled, a **Web Search** card will appear on the Domain Overview tab, and a **Web Search** sub-tab will be available under the **Data Sources** tab.

<Frame>
  <img alt="Image" />

  <img alt="Image" />
</Frame>

## 2. Configure the source policy

After enabling Web Search, you can control which websites WisdomAI is allowed to search. This is configured through the **Source Policy** on the Web Search configuration page.

1. Go to your **Domain** > **Data Sources** tab > **Web Search** sub-tab.
2. Under **Source Policy**, select one of the three options:

| Policy                            | Description                                                                       |
| :-------------------------------- | :-------------------------------------------------------------------------------- |
| **Include all domains**           | WisdomAI can search any website. This is the default.                             |
| **Include only specific domains** | WisdomAI will only return results from the listed domains (allowlist).            |
| **Exclude specific domains**      | WisdomAI will return results from all domains except the listed ones (blocklist). |

<Warning>
  **Include only specific domains** and **Exclude specific domains** are mutually exclusive — you can only use one at a time.
</Warning>

3. If you selected **Include only specific domains** or **Exclude specific domains**, add the domains you want to include or exclude:
   * Click **Add domain** to add a new entry.
   * Enter the domain in apex form (e.g., `example.com`).
   * You can add up to **10 domains**, one per entry.
4. Click **Save Configuration**.

<Frame>
  <img alt="Image" />

  <img alt="Image" />
</Frame>

### Domain format guidelines

When entering domains in the source policy, follow these rules:

* Use apex domain form: `example.com`, `wikipedia.org`
* Subdomains are supported: `subdomain.example.gov`
* Bare domain extensions starting with a period are allowed: `.gov`, `.edu`, `.co.uk`
* Do **not** include URL schemes (`http://`, `https://`)
* Do **not** include `www.` prefixes
* Paths are **not** supported (e.g., `example.com/blog` is invalid)

## How web search works in chat

WisdomAI uses two tools behind the scenes:

* **Web Search**: Searches the web for information relevant to a user's question, returning results with titles, URLs, and content excerpts.
* **Web Fetch**: Fetches and extracts content from specific web page URLs.

<Info>
  Web Search is an AI-driven tool. WisdomAI decides **when** to invoke web search or fetch based on the user's question. You do not need to explicitly request a web search — if the question benefits from external information, WisdomAI will automatically search the web.
</Info>

When WisdomAI decides to use the web:

1. It calls the **web search** tool with a search objective and optional keyword queries.
2. Results are returned with titles, URLs, publish dates, and content excerpts.
3. If it needs more detail from a specific page, it calls the **web fetch** tool to extract the page content.
4. It synthesizes the web results into a response with **inline citations** and a **Sources** section listing all referenced URLs.

<Info>
  Web Fetch can only access publicly available pages. It **cannot** access content behind login walls, authentication gates, or private documents (e.g., private Google Docs).
</Info>

## Next steps

<CardGroup>
  <Card title="Connect Unstructured Repositories" icon="folder-plus" href="/improve-wisdom-ai-responses/connect-unstructed-repositories-datasets">
    Integrate unstructured data sources, such as documents or knowledge bases, to enrich your analysis.
  </Card>

  <Card title="Connect and Test Tutorial" icon="rocket" href="/setting-up-wisdom-ai/basic-tutorial-connect-and-test">
    Walk through the initial setup to connect a data source and run your first query.
  </Card>

  <Card title="Advanced Data Modeling" icon="sitemap" href="/setting-up-wisdom-ai/advanced-data-modeling-creating-context">
    Define relationships and context in your data to enable more powerful analysis.
  </Card>
</CardGroup>


# Set up a GCP service account for WisdomAI
Source: https://docs.wisdom.ai/getting-started/connect-data-sources/set-up-gcp-service-account



WisdomAI uses a Google Cloud Platform (GCP) service account to authenticate with BigQuery for background operations such as metadata crawling and data discovery. This guide walks you through creating the service account, assigning the required IAM roles, and generating the JSON key that WisdomAI needs to connect.

## Prerequisites

* An active Google Cloud project
* The BigQuery API enabled in that project
* Permission to create service accounts and assign IAM roles in your GCP project

## Create the service account

A service account is a Google account that an application uses to make authorized API calls on its own behalf.

1. Open the GCP Console and go to **IAM & Admin** > **Service Accounts**.
2. Click **+ CREATE SERVICE ACCOUNT**.
3. Enter a descriptive **Service account name**, for example `Wisdom-bigquery`. The **Service account ID** is generated automatically from the name.
4. Optionally, add a **Service account description** such as `Service account for WisdomAI BigQuery connectivity`.
5. Click **CREATE AND CONTINUE**.

## Assign IAM roles

WisdomAI needs three roles to read metadata, run queries, and stream results efficiently from BigQuery:

* **BigQuery Data Viewer**: view BigQuery data and metadata
* **BigQuery Job User**: run BigQuery jobs, including queries
* **BigQuery Read Session User**: retrieve data efficiently through the BigQuery Storage API

Assign these roles at the project level for broad access:

1. On the **Grant this service account access to project** step, open the **Select a role** dropdown.
2. Add **BigQuery Data Viewer**, **BigQuery Job User**, and **BigQuery Read Session User**.
3. Click **DONE**.

### Restrict access to specific datasets

If you want WisdomAI to access only certain datasets in your project, grant data roles at the dataset level instead of the project level.

1. Open BigQuery in the GCP Console and select the dataset you want to share.
2. Click **SHARE DATASET**.
3. In the **Add principals** field, enter the email address of the service account.
4. Assign **BigQuery Data Viewer** and **BigQuery Read Session User** to the service account for this dataset.
5. Repeat for every dataset WisdomAI needs to access.
6. Assign **BigQuery Job User** once at the project level. This role cannot be granted at the dataset level.

## Generate a JSON key

WisdomAI authenticates with BigQuery using a JSON key file associated with the service account.

1. Go back to **IAM & Admin** > **Service Accounts** and click the service account you created.
2. Open the **KEYS** tab.
3. Click **ADD KEY** > **Create new key**.
4. Select **JSON** as the key type and click **CREATE**.

The key file downloads to your computer.

<Warning>
  The JSON key file contains sensitive credentials. Treat it like a password: store it in a secrets manager or secure file-sharing tool, and never send it over unencrypted email or chat.
</Warning>

## Next steps

<CardGroup>
  <Card title="Connect to Google BigQuery" icon="database" href="/getting-started/connect-data-sources/connect-to-google-bigquery">
    Use the service account to create a BigQuery connection in WisdomAI.
  </Card>

  <Card title="Connect to Snowflake" icon="snowflake" href="/getting-started/connect-data-sources/connect-to-snowflake">
    Connect to Snowflake directly or via a proxy using key-pair authentication.
  </Card>
</CardGroup>


# Supported Data Sources
Source: https://docs.wisdom.ai/getting-started/connect-data-sources/supported-data-sources



This page covers the data sources that can be connected to WisdomAI, including databases, data warehouses, and Files (PDFs, PPTs, Docs). It outlines the connection requirements, necessary configurations, and troubleshooting tips for seamless integration.

WisdomAI works with the following data sources:

## Warehouse & Database sources

* PostgreSQL
* Microsoft SQL Server
* MySQL
* Oracle
* Databricks
* Snowflake
* Google BigQuery
* Google Cloud Spanner
* Amazon Redshift
* Amazon Athena
* Teradata
* Azure Synapse & Synapse Serverless
* ClickHouse (Beta)
* Trino (Beta)
* CSV files

<Warning>
  **Note on Syncing**: After successfully adding a connection, the initial sync may take a few minutes to complete before data is available for analysis.
</Warning>

## File & Repository sources

* Amazon S3
* Google Cloud Storage (GCS)
* Azure Blob Storage
* SharePoint
* Direct upload
* GitHub

Supported file types: PDFs, DOC/DOCX files, PowerPoint files, txt files, and images.

To learn how to connect to your Data Sources, read the [Basic Tutorial: Connect and Test](/setting-up-wisdom-ai/basic-tutorial-connect-and-test).

### Connection requirements

This section outlines common prerequisites for connecting to data sources. Specific requirements are detailed under each data source.

* **Network Access:** Ensure WisdomAI has network access to your database or data warehouse host. This may involve configuring firewall rules or security groups.
* **Authentication Details:** You will need the correct credentials (username, password, keys, etc.) for your chosen data source.
* **SSL/TLS Configuration:** For secure connections, ensure your database/data warehouse is configured to accept SSL/TLS connections, and configure WisdomAI accordingly (e.g., `SSL Mode: require` for PostgreSQL).
* **Service Accounts (Google BigQuery):** A Google Cloud service account with appropriate BigQuery permissions is required.
  <Info>
    For PostgreSQL and Amazon Redshift, you can optionally configure an SSH Tunnel to connect through a bastion host.
  </Info>

<Tabs>
  <Tab title="PostgreSQL">
    The following table lists the requirements you must provide when connecting to PostgreSQL.

    <Note>
      If your database is protected by a firewall or network access policies, allowlist both of WisdomAI's CIDR blocks (35.238.115.103/32 and 34.82.248.105/32).
    </Note>

    <Info>
      SSH settings are optional.
    </Info>

    | Requirement              | Description                                                              |
    | :----------------------- | :----------------------------------------------------------------------- |
    | Host                     | Server address or IP                                                     |
    | Port                     | Typically `5432`                                                         |
    | Database                 | Name of the database                                                     |
    | Username                 | Database user with read access                                           |
    | Password                 | User's password                                                          |
    | SSH Host                 | Hostname or IP address of the bastion host (Optional)                    |
    | SSH Port                 | Port number on the SSH host (Optional)                                   |
    | SSH Username             | The username required to log in to the bastion host (Optional)           |
    | Authentication Method    | You can authenticate using either a Private Key or a Password (Optional) |
    | SSH Private Key/Password | The Private Key or Password used for the SSH authentication (Optional)   |

    Find below an example connection:

    ```txt theme={null}
    Host: postgres.example.com
    Port: 5432
    Database: analytics
    Username: wisdom_reader
    Password: ********
    SSL Mode: require
    ```
  </Tab>

  <Tab title="Microsoft SQL Server">
    The following table lists the requirements you must provide when connecting to Microsoft SQL Server.

    <Note>
      If your database is protected by a firewall or network access policies, allowlist both of WisdomAI's CIDR blocks (35.238.115.103/32 and 34.82.248.105/32).
    </Note>

    | Requirement              | Description                                   |
    | :----------------------- | :-------------------------------------------- |
    | Server                   | SQL Server address or instance name           |
    | Port                     | Typically `1433`                              |
    | Database                 | Name of the database                          |
    | Authentication           | SQL Server or Windows Authentication          |
    | Username                 | SQL Server login with read access             |
    | Password                 | Login password                                |
    | Trust Server Certificate | Whether to trust the server's SSL certificate |

    Here's an example connection:

    ```txt theme={null}
    Server: sqlserver.example.com
    Port: 1433
    Database: business_data
    Authentication: SQL Server
    Username: wisdom_reader
    Password: ********
    Trust Server Certificate: True
    ```
  </Tab>

  <Tab title="Databricks">
    The following table lists the requirements you must provide when connecting to Databricks.

    <Note>
      If your database is protected by a firewall or network access policies, allowlist both of WisdomAI's CIDR blocks (35.238.115.103/32 and 34.82.248.105/32).
    </Note>

    | Requirement     | Description                      |
    | :-------------- | :------------------------------- |
    | Server Hostname | Databricks SQL endpoint hostname |
    | HTTP Path       | HTTP path for the SQL endpoint   |
    | Username        | Databricks username              |
    | Password        | Databricks password              |
    | Catalog         | Optional Databricks catalog name |
    | Schema          | Optional schema name             |

    Below is an example key pair connection:

    ```txt theme={null}
    Server Hostname: dbc-xxxx-yyyy.cloud.databricks.com
    HTTP Path: /sql/1.0/warehouses/abcdef123456
    Username: wisdom_user
    Password: ********
    Catalog: main
    Schema: default
    ```
  </Tab>

  <Tab title="Snowflake">
    The following table lists the requirements you must provide when connecting to Snowflake.

    <Note>
      If your database is protected by a firewall or network access policies, allowlist both of WisdomAI's CIDR blocks (35.238.115.103/32 and 34.82.248.105/32).
    </Note>

    | Requirement      | Description                           |
    | :--------------- | :------------------------------------ |
    | Account          | Snowflake account identifier          |
    | Username         | Snowflake user with access privileges |
    | Private Key File | Private Key File                      |
    | Warehouse        | Compute warehouse to use              |
    | Database         | Database name                         |
    | Schema           | Schema name (optional)                |
    | Role             | User role (optional)                  |

    To set up key pair authentication for Snowflake:

    1. Generate an RSA key pair (2048-bit minimum length).
    2. Register the public key with your Snowflake user.
    3. Use the private key (PEM format) when creating a WisdomAI connection.

    Here's an example key pair connection:

    ```txt theme={null}
    Account: xy12345.us-east-1
    Username: wisdom_analytics
    Private Key File: Upload your private key file (.p8 or .pem format)
    Warehouse: ANALYTICS_WH
    Database: BUSINESS_DATA
    Schema: PUBLIC
    Role: ANALYST_ROLE
    ```

    Access the [Snowflake Docs](https://docs.snowflake.com/en/user-guide/key-pair-auth.html) to get more information about Key Pair Authentication.
  </Tab>

  <Tab title="Google BigQuery">
    The following table lists the requirements you must provide when connecting to Google BigQuery.

    | Requirement    | Description                       |
    | :------------- | :-------------------------------- |
    | Project ID     | Google Cloud project identifier   |
    | Authentication | Service account key (JSON format) |
    | Dataset        | Default dataset (optional)        |

    Find below an example connection:

    ```txt theme={null}
    Project ID: my-analytics-project-123
    Authentication: Upload service account key JSON file
    Dataset: analytics_data
    ```

    <Warning>
      You'll need to create a service account in Google Cloud with appropriate permissions on the BigQuery datasets you want to access.
    </Warning>
  </Tab>

  <Tab title="Amazon Redshift">
    The following table lists the requirements you must provide when connecting to Amazon Redshift.

    <Note>
      If your database is protected by a firewall or network access policies, allowlist both of WisdomAI's CIDR blocks (35.238.115.103/32 and 34.82.248.105/32).
    </Note>

    <Info>
      SSH settings are optional.
    </Info>

    | Requirement              | Description                                                              |
    | :----------------------- | :----------------------------------------------------------------------- |
    | Host                     | Redshift cluster endpoint                                                |
    | Port                     | Typically `5439`                                                         |
    | Database                 | Database name                                                            |
    | Username                 | Database user with read access                                           |
    | Password                 | User password                                                            |
    | Schema                   | Schema name (Optional)                                                   |
    | SSH Host                 | Hostname or IP address of the bastion host (Optional)                    |
    | SSH Port                 | Port number on the SSH host (Optional)                                   |
    | SSH Username             | The username required to log in to the bastion host (Optional)           |
    | Authentication Method    | You can authenticate using either a Private Key or a Password (Optional) |
    | SSH Private Key/Password | The Private Key or Password used for the SSH authentication (Optional)   |
  </Tab>

  <Tab title="CSV Files">
    You can also upload CSV files to a Domain. Here are the requirements for these files:

    * File must be in a valid CSV format
    * Maximum file size: 100MB
    * UTF-8 encoding recommended
    * Headers should be in the first row

    To learn how to upload them, read [Upload CSV files](/setting-up-wisdom-ai/basic-tutorial-connect-and-test#3-upload-csv-files-optional).
  </Tab>

  <Tab title="Amazon Athena">
    The following table lists the requirements you must provide when connecting to Amazon Athena.

    | Requirement           | Description                                                                                 |
    | :-------------------- | :------------------------------------------------------------------------------------------ |
    | AWS Access Key ID     | The access key for an IAM user with permissions to access Athena and the underlying S3 data |
    | AWS Secret Access Key | The secret access key associated with the AWS Access Key ID                                 |
    | Region Name           | The AWS region where your Athena service is hosted                                          |
    | S3 Staging Directory  | The S3 bucket path where Athena stores query results                                        |
    | Work Group            | The specific Athena workgroup used to run queries                                           |

    Here's an example connection:

    ```txt theme={null}
    AWS Access Key ID: AKIAIOSFODNN7EXAMPLE
    AWS Secret Access Key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
    Region Name: us-west-2
    S3 Staging Directory: s3://wisdomai-athena-results-bucket/
    Work Group: primary
    ```
  </Tab>

  <Tab title="Azure Synapse">
    The following table lists the requirements you must provide when connecting to Azure Synapse.

    <Note>
      If your database is protected by a firewall or network access policies, allowlist both of WisdomAI's CIDR blocks (35.238.115.103/32 and 34.82.248.105/32).
    </Note>

    | Requirement            | Description                                                                 |
    | :--------------------- | :-------------------------------------------------------------------------- |
    | Workspace SQL endpoint | The SQL endpoint URL for your workspace                                     |
    | Subscription ID        | The ID of your Azure subscription                                           |
    | Resource Group ID      | The name of the Azure resource group where the Synapse workspace is located |
    | Workspace ID           | The ID for the Synapse Analytics workspace                                  |
    | Client ID              | The Application ID of the Azure Service Principal used for authentication   |
    | Tenant ID              | The Directory ID of your Azure Active Directory                             |
    | Client Secret          | The secret value generated for the Service Principal                        |

    Here's an example connection:

    ```txt theme={null}
    Workspace SQL endpoint: synapse-prod-ondemand.sql.azuresynapse.net
    Subscription ID: a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6
    Resource Group ID: rg-analytics-prod
    Workspace ID: synapse-workspace-01
    Client ID: 00000000-0000-0000-0000-000000000000
    Tenant ID: ffffffff-ffff-ffff-ffff-ffffffffffff
    Client Secret: ********
    ```
  </Tab>

  <Tab title="Azure Synapse Serverless">
    The following table lists the requirements you must provide when connecting to Azure Synapse Serverless.

    <Note>
      If your database is protected by a firewall or network access policies, allowlist both of WisdomAI's CIDR blocks (35.238.115.103/32 and 34.82.248.105/32).
    </Note>

    | Requirement             | Description                                                               |
    | :---------------------- | :------------------------------------------------------------------------ |
    | Serverless SQL endpoint | The on-demand SQL endpoint for your Synapse workspace                     |
    | Client ID               | The Application ID of the Azure Service Principal used for authentication |
    | Tenant ID               | The Directory ID of your Azure Active Directory                           |
    | Client Secret           | The client secret value generated for the Service Principal               |

    Here's an example connection:

    ```txt theme={null}
    Serverless SQL endpoint: my-workspace-ondemand.sql.azuresynapse.net
    Client ID: 00000000-0000-0000-0000-000000000000
    Tenant ID: ffffffff-ffff-ffff-ffff-ffffffffffff
    Client Secret: ********
    ```
  </Tab>

  <Tab title="Azure Blob Storage">
    The following table lists the requirements you must provide when connecting to Azure Blob Storage.

    | Requirement          | Description                                                 |
    | :------------------- | :---------------------------------------------------------- |
    | Storage Account Name | The name of your Azure Storage account                      |
    | Container Name       | The specific blob container where your data is stored       |
    | Connection String    | The Azure Storage connection string used for authentication |

    Here's an example connection:

    ```txt theme={null}
    Storage Account Name: wisdomstorageaccount
    Container Name: customer-data
    Connection String: DefaultEndpointsProtocol=https;AccountName=wisdomstorageaccount;AccountKey=xxxxxx...xxxxxx;EndpointSuffix=core.windows.net
    ```
  </Tab>

  <Tab title="ClickHouse">
    The following table lists the requirements you must provide when connecting to ClickHouse.

    <Note>
      If your database is protected by a firewall or network access policies, allowlist both of WisdomAI's CIDR blocks (35.238.115.103/32 and 34.82.248.105/32).
    </Note>

    | Requirement | Description                                                |
    | :---------- | :--------------------------------------------------------- |
    | Host        | The hostname or IP address of your ClickHouse server       |
    | Port        | The port number used for the connection                    |
    | Username    | The database user account with read access to the metadata |
    | Password    | The password for the specified database user               |

    <Note>
      Database filters are optional, but it is recommended to specify only the databases that you want to expose to Wisdom.
    </Note>

    Here's an example connection:

    ```txt theme={null}
    Host: ch-cluster.example.com
    Port: 8123
    Username: wisdom_scanner
    Password: ********
    Database filters: sales_data, inventory_records
    ```
  </Tab>

  <Tab title="Trino">
    The following table lists the requirements you must provide when connecting to Trino.

    <Note>
      If your database is protected by a firewall or network access policies, allowlist both of WisdomAI's CIDR blocks (35.238.115.103/32 and 34.82.248.105/32).
    </Note>

    | Requirement                       | Description                                                                               |
    | :-------------------------------- | :---------------------------------------------------------------------------------------- |
    | Host                              | The hostname or IP address of your Trino coordinator node                                 |
    | Port                              | The port number used for the connection                                                   |
    | Username                          | The user account with appropriate permissions to access the catalogs                      |
    | Password                          | The password for the specified user account                                               |
    | Use SSL (HTTPS)                   | Toggle to enable secure communication via SSL                                             |
    | Skip SSL Certificate Verification | If enabled, WisdomAI will not validate the SSL certificate (common for self-signed certs) |
    | Force HTTPS                       | Forces the connection to use HTTPS even if the endpoint suggests otherwise                |

    <Note>
      Catalog filters are optional, but it is recommended to specify only the catalogs and their schemas that you want to expose to Wisdom.
    </Note>

    Here's an example connection:

    ```txt theme={null}
    Host: trino.internal.company.com
    Port: 8443
    Username: query_service
    Password: ********
    Use SSL (HTTPS): True
    Skip SSL Certificate Verification: False
    Force HTTPS: True
    Catalog Filters: snowflake_prod, glue_catalog
    ```
  </Tab>

  <Tab title="SharePoint">
    The following table lists the requirements you must provide when connecting to SharePoint.

    | Requirement   | Description                                                         |
    | :------------ | :------------------------------------------------------------------ |
    | Client ID     | The client ID of the Azure App registration used for authentication |
    | Tenant ID     | The Directory ID of your Azure Active Directory                     |
    | Client Secret | The client secret value generated for the Azure App registration    |
    | Site URL      | The full URL of the SharePoint site you want to crawl               |

    <Note>
      By default, all document libraries are crawled. It is recommended to specify only the libraries that you want to expose to Wisdom in the **Document Libraries** field.
    </Note>

    Here's an example connection:

    ```txt theme={null}
    Client ID: 00000000-0000-0000-0000-000000000000
    Tenant ID: ffffffff-ffff-ffff-ffff-ffffffffffff
    Client Secret: ********
    Site URL: https://website.sharepoint.com/sites/internal-knowledge
    Document Libraries: Policies, Procedures
    ```
  </Tab>

  <Tab title="Google Cloud Spanner">
    The following table lists the requirements you must provide when connecting to Google Cloud Spanner.

    | Requirement               | Description                                                     |
    | :------------------------ | :-------------------------------------------------------------- |
    | Project ID                | The unique identifier for your Google Cloud Project             |
    | Instance ID               | The ID of the Cloud Spanner instance                            |
    | Database ID               | The ID of the specific database within the Spanner instance     |
    | Service Account Info JSON | The complete contents of your GCP service account JSON key file |

    Here's an example connection:

    ```txt theme={null}
    Project ID: majestic-project-12345
    Instance ID: spanner-instance-main
    Database ID: inventory_db
    Service Account Info JSON: { "type": "service_account", "project_id": "majestic-project-12345", ... }
    ```
  </Tab>

  <Tab title="Teradata">
    The following table lists the requirements you must provide when connecting to Teradata.

    | Requirement | Description                                                 |
    | :---------- | :---------------------------------------------------------- |
    | Host        | The hostname or IP address of your Teradata server          |
    | Port        | The port number used for the connection, typically `1025`   |
    | Username    | The database user account with appropriate read permissions |
    | Password    | The password for the specified database user                |

    <Note>
      **Database filters** are optional, but it is recommended to specify only the databases that you want to expose to Wisdom.
    </Note>

    Here's an example connection:

    ```txt theme={null}
    Host: td-prod.example.com
    Port: 1025
    Username: wisdom_read_only
    Password: ********
    Database filters: sales_v, marketing_v
    ```
  </Tab>

  <Tab title="GitHub">
    The following table lists the requirements you must provide when connecting to GitHub.

    | Requirement           | Description                                                         |
    | :-------------------- | :------------------------------------------------------------------ |
    | Connection name       | A name to identify this connection                                  |
    | Repository URL        | The URL of the repository you want WisdomAI to extract context from |
    | Personal access token | Required for private repositories                                   |
    | Branch                | The branch WisdomAI should crawl                                    |

    <Note>
      A personal access token is required for private repositories.
    </Note>

    Here's an example connection:

    ```txt theme={null}
    Connection name: product-docs-repo
    Repository URL: https://github.com/your-org/your-repo
    Personal access token: ********
    Branch: main
    ```
  </Tab>
</Tabs>

***

## Protocol-based source: MCP server

Connect to any server that implements the [Model Knowledge Protocol](https://modelcontextprotocol.io). MCP enables WisdomAI to fetch real-time data and scan metadata from external systems through a standardized protocol.

### MCP server requirements

To connect an MCP server, you must provide:

| Requirement            | Description                                         |
| :--------------------- | :-------------------------------------------------- |
| **Transport Type**     | Streamable HTTP, Server-Sent Events (SSE), or STDIO |
| **Server URL/Command** | The endpoint or command used to run the MCP server  |
| **Auth Type**          | API Key, OAuth, or None                             |

<Info>
  For detailed setup instructions, see [Connect an MCP Server](/getting-started/connect-data-sources/connect-mcp-server).
</Info>

## Web search

WisdomAI can search the internet and fetch content from public web pages as a data source. When enabled on a domain, the AI automatically supplements its answers with real-time web information — such as industry benchmarks, market trends, or publicly available reference material.

Web Search is configured per domain with an optional **source policy** that controls which websites WisdomAI can search (allowlist or blocklist up to 10 domains).

<Info>
  For detailed setup instructions, see [Search the Web](/getting-started/connect-data-sources/search-the-web).
</Info>

## Integrations

Connect WisdomAI to your essential business applications and services to unlock deeper insights from all your data.

### ETL integration for SaaS applications

WisdomAI works with leading (Extract, Transform, and Load) ETL partners to provide data integration from various SaaS applications.

WisdomAI leverages **Fivetran** or **Airbyte** to ETL data from SaaS applications into a customer-owned data warehouse or, alternatively, into a WisdomAI-managed **BigQuery**-based analytics environment.

### Supported SaaS data sources

A non-exhaustive list of SaaS Sources includes:

* CRM tools (Salesforce, Hubspot)
* Financial systems (NetSuite)
* Ticketing systems (Jira, Zendesk)
* Marketing platforms (Google Analytics, Facebook Ads)

### Setting up SaaS integration

To integrate data from SaaS applications, please contact WisdomAI support at `support@askwisdom.ai`. Our team will work with you to set up the appropriate ETL pipelines using our partner technologies.

## Limits

This section details any known limitations or restrictions when connecting to data sources.

* **File Size:** The Maximum file size for direct upload is 100MB. For larger files or datasets, consider uploading them to a data warehouse or cloud storage (e.g., Amazon S3, Google Cloud Storage) and connecting WisdomAI to the warehouse/storage.
* **Query Limits:** Be aware of any rate limits or query concurrency limits imposed by your database or data warehouse provider. WisdomAI's queries will contribute to these limits.
* **Data Type Support:** While WisdomAI strives to support a wide range of data types, some highly specialized or proprietary data types might require specific handling or may not be fully supported. Contact us if you request any assistance.

## Troubleshooting

Understand common problems and systematic troubleshooting techniques that can help you quickly identify and resolve connectivity issues.

### Common connection issues

| **Issue**             | **Possible Causes**                                                                 | **Resolution**                                                                                             |
| --------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Connection Timeout    | - Network latency  <br /> - Firewall blocking  <br /> - Server overload             | - Check network connectivity  <br /> - Verify firewall rules  <br /> - Increase connection timeout setting |
| Authentication Failed | - Incorrect credentials  <br /> - Expired API keys/tokens  <br /> - Account lockout | - Verify username/password  <br /> - Regenerate API keys  <br /> - Check account status                    |
| Permission Denied     | - Insufficient privileges  <br /> - IP restriction  <br /> - Resource access limits | - Update user permissions  <br /> - Whitelist IP addresses  <br /> - Check resource quotas                 |

For persistent connection issues, contact WisdomAI support at `support@askwisdom.ai` with the connection ID and error logs for assistance.

## Next steps

<CardGroup>
  <Card title="Connect Unstructured Repositories" icon="folder-plus" href="/improve-wisdom-ai-responses/connect-unstructed-repositories-datasets">
    Integrate unstructured data sources, such as documents or knowledge bases, to enrich your analysis.
  </Card>

  <Card title="Connect and Test Tutorial" icon="rocket" href="/setting-up-wisdom-ai/basic-tutorial-connect-and-test">
    Walk through the initial setup to connect a data source and run your first query.
  </Card>

  <Card title="Advanced Data Modeling" icon="sitemap" href="/setting-up-wisdom-ai/advanced-data-modeling-creating-context">
    Define relationships and context in your data to enable more powerful analysis.
  </Card>
</CardGroup>


# Glossary
Source: https://docs.wisdom.ai/getting-started/glossary



Find here a list of key terms used throughout the Wisdom AI product and documentation. Use it as a quick reference to ensure a shared vocabulary across Admins, Data Admins and Explorers.

## A

**Administrator / Admin**: Highest-privilege user role with full access to connect data sources, configure domains, manage security, and govern the rollout of WisdomAI. Also responsible for foundational setup and governance, including user, domain, data source, data model, and knowledge management, as well as accessing dashboards and reports, monitoring, and auditing.

**Agentic Analytics**: A multi-step analytic workflow executed by an internal planning agent that decomposes complex questions into sub-queries and composes the final answer automatically.

**Analysis Plan**: The intermediate set of steps (SQL, transformations, visualisations) generated by WisdomAI when executing Agentic Analytics.

**Answer Accuracy Score**: A system metric that tracks the percentage of answers receiving positive feedback (👍) versus total answers served, used to judge readiness for roll-out.

**Audit Logs**: Records of events within the WisdomAI system, used to track usage and monitor platform health.

## B

**Build Dashboards (Dashboards)**: The capability to create and maintain Dashboards (WisdomAI's term for dashboards), including dashboards and domain-specific assets.

## C

**Chat Analytics**: Conversational, natural-language interaction mode where users ask questions and receive answers in real time.

**Column-Level Security**: A granular access control mechanism that restricts user access to specific columns within a data table.

**Connector**: Reusable integration module that handles authentication and data extraction for a specific database, warehouse, or SaaS application.

**Continuous Learning**: WisdomAI’s process of improving answer quality over time based on feedback, reviewed queries, and added context.

**Knowledge Enhancement**: The act of supplying extra business logic, synonyms, or documentation so the NLQ engine produces domain-specific answers.

## D

**Data Administrator**: A role with privileges focused on domain and data-model maintenance but without full system-wide admin rights. They can connect domain-level data, model business context, manage content, apply data policies, and collaborate with Explorers.

**Data Dictionary**: Human-readable catalogue of domain tables, columns, metrics, and their business definitions.

**Data Model Augmentation**: Enhancing the semantic model with derived fields, entities, or metrics to create richer answers.

**Data Source**: Any origin from which WisdomAI ingests data (database, warehouse, CSV, SaaS API, etc.).

**Data Warehouse**: Centralised analytical database (e.g., Snowflake, BigQuery) commonly used as a primary data source.

**Derived Column**: A calculated column added to a table or view within a domain, not present in the raw source.

**Derived Table**: A table produced from transformations or joins on raw tables, materialised or virtual, and added to the semantic model.

**Domain**: A dedicated, configurable space within the platform designed to represent a specific business area or dataset. It functions as the core container for your data sources, business knowledge (including context, metrics, and entities), and settings, enabling you to connect data, apply business logic, and fine-tune the AI for accurate and relevant data analysis responses.

**Domain Management**: The capability to configure and maintain organizational domains within WisdomAI.

**Domain-Level Permissions**: Fine-grained access rules that determine who can query or edit each domain.

## E

**Embedded Analytics**: Mechanism for embedding WisdomAI Dashboards or charts into external applications via iframe or public link.

**Entity**: A business object represented in the semantic model (e.g., *Customer*, *Order*); usually maps to a primary-key table.

**Explorer**: End-user role focused on asking questions, creating Dashboards, and sharing insights; cannot access admin configuration. They can ask questions, explore stories, share insights, save views, and utilize knowledge management, including access to dashboards and reports.

## F

**Feedback Loop**: Cycle in which user feedback (👍/👎, edits, reviewed queries) trains WisdomAI to improve future answers.

**Fork (Chats)**: Create an independent copy of a chat or Dashboard so it can be modified without affecting the original.

## G

**Go/No-Go Demo**: Validation checkpoint where Admins present curated dashboards to stakeholders to decide if WisdomAI is ready for wider release.

**Governance**: Set of policies and controls that maintain data integrity, security, and compliance within WisdomAI.

## L

**Limits & Quotas**: System-enforced maximums on rows processed, file sizes, API calls, or concurrent queries.

## M

**Metric**: Quantitative measure (e.g., *total revenue*, *active users*) defined in the semantic model and calculated by WisdomAI.

**Monitoring Dashboard**: Admin-only Dashboard that surfaces operational KPIs such as sync latency and answer accuracy.

## N

**Natural-Language Query (NLQ)**: An end-user question expressed in everyday language, parsed and converted to SQL by WisdomAI.

## P

**Python Intepreter Tool**: Feature that uses AI-generated Python code to perform advanced data science operations—such as forecasting, regression, clustering, and mathematical calculations—directly from natural-language questions in Chat.

**Phased Roll-out**: Controlled deployment approach that starts with a pilot domain and gradually expands to more data and users.

**Prompt Template**: Preset wording used to influence the NLQ engine’s tone, terminology, or calculation logic.

## Q

**Query Pattern**: Reusable example or phrasing that teaches users how to ask effective questions (e.g., “Show *metric* by *dimension* for last *n* days”).

## R

**Reports**: Formal presentations of data and analysis, accessible by various roles.

**Reviewed Query**: An NLQ that has been checked by an Admin, corrected if necessary, and saved as a trusted reference.

**Role-Based Access Control (RBAC)**: A security model where permissions are organized around roles, and users are assigned to roles, ensuring appropriate access based on responsibilities.

**Row-Level Access Control (RLAC)**: Rules that restrict data visibility at the row level based on user attributes (e.g., region).

## S

**Scheduled Dashboard**: Dashboard or chart automatically sent at a defined cadence via email or Slack.

**Schemas**: The structure of tables and relationships within a database or data source.

**Semantic Model**: Layer that abstracts raw tables into business-friendly entities, metrics, relationships, and dimensions.

**Sharing Model**: Framework that governs who can view, edit, fork, or subscribe to content within WisdomAI.

**Dashboards**: WisdomAI’s term for a dashboard: a collection of answer cards and visualisations saved with a title and description.

**Subscription**: User opt-in to receive scheduled Dashboard deliveries or notifications.

**Sync Latency**: Elapsed time between the source data change and its availability in WisdomAI after the latest sync.

## T

**Tenant / Environment**: Isolated instance of WisdomAI (with its own domains, users, and settings) provisioned for a single customer or business unit.

**Thumbs-Up / Thumbs-Down**: Simple feedback buttons that signal whether an answer was helpful and drive the Continuous Learning process.

## U

**Usage Metrics**: Data points that measure how the WisdomAI platform is being used, contributing to monitoring system health.

## W

**Webhook**: HTTP callback that triggers an external system when certain events occur in WisdomAI (e.g., Dashboard published, data sync complete).


# How WisdomAI Works
Source: https://docs.wisdom.ai/getting-started/how-wisdom-ai-works



WisdomAI is a platform that helps businesses analyze their data and make informed decisions. It allows users to ask questions in plain English and receive clear, data-driven answers and visualizations, without the need for coding or manual dashboard creation.

## What does WisdomAI do?

WisdomAI transforms your company's raw data into actionable insights through several key capabilities:

<Columns>
  <Card title="Understands Your Questions" icon="comments">
    You can ask questions in everyday language, like "What was our revenue last quarter?" or "Which products are selling best?" WisdomAI uses advanced Natural-Language Query (NLQ) to understand what you're asking.
  </Card>

  <Card title="Connects to Your Data" icon="database">
    It seamlessly connects to various data sources your business uses, such as databases like PostgreSQL and SQL Server, or data warehouses like Snowflake and Google BigQuery.
  </Card>
</Columns>

<Columns>
  <Card title="Organizes Your Business Data" icon="sitemap">
    WisdomAI helps you organize your data into domains that represent different parts of your business, like Sales or Marketing. This makes your data more relevant and easier for everyone to use.
  </Card>

  <Card title="Turns Answers into Dashboards" icon="chart-simple">
    Instead of just giving you numbers, WisdomAI can create interactive Dashboards with charts and text. They are automatically updated as your data changes, making it easy to share insights across your team.
  </Card>
</Columns>

<Columns>
  <Card title="Automates Workflows" icon="robot">
    You can set up Agents to automate everyday analytical tasks, from recurring analyses to threshold-based alerts, so your team gets answers without having to ask.
  </Card>

  <Card title="Learns and Improves" icon="lightbulb">
    WisdomAI continually improves its capabilities based on user feedback. When you provide corrections or refine questions, the system learns to give even better answers in the future.
  </Card>
</Columns>

This means WisdomAI helps you quickly get the information you need from your data, making data-driven decisions simpler and faster for everyone.

## Who uses WisdomAI?

WisdomAI is designed for businesses of all sizes, from small startups to large corporations, across various industries. It's intended to be useful for different roles within your organization:

<Columns>
  <Card title="Admins" icon="screwdriver-wrench">
    These are typically IT or BI directors who set up WisdomAI, connect it to your data sources, manage user access, and define the overall data structure on the platform.
  </Card>

  <Card title="Explorers" icon="users">
    This group comprises business users, executives, and other stakeholders who utilize WisdomAI to ask questions in natural language, create and view Dashboards, share insights with their team, and subscribe to scheduled updates.
  </Card>
</Columns>

<Card title="Developers" icon="code">
  Software engineers and technical teams who build on top of WisdomAI — embedding dashboards into products, managing users via the API, or connecting WisdomAI to AI tools.
</Card>

<Tip>
  This documentation is organized to help you focus on what matters most in your role. For more information on each role, visit the [Where to Start](/getting-started/overview#where-to-start) section.
</Tip>

## WisdomAI vs generic RAG systems

Unlike generic Retrieval-Augmented Generation (RAG) solutions that rely purely on embedding search over documents, WisdomAI builds a structured understanding of your data through semantic modeling, curated context, and validated logic.

| **Feature**                       | **WisdomAI** | **Generic RAG** |
| --------------------------------- | ------------ | --------------- |
| Understands data relationships    | ✅            | ❌               |
| Requires semantic modeling        | ✅            | ❌               |
| Validated, testable logic         | ✅            | ❌               |
| Dynamic, auto-updating dashboards | ✅            | ❌               |
| Tailored for business data        | ✅            | ❌               |

<Tip>
  WisdomAI is purpose-built for enterprise analytics, not just document Q\&A.
</Tip>

## Data flow & architecture overview

WisdomAI transforms your business data into actionable insights using a multi-layered pipeline. The following components work together to deliver accurate, contextualized answers and auto-updating Dashboards.

<Frame>
  <img alt="Data Sources Flow Connect Pn" />

  <img alt="Data Sources Flow Connect Pn" />
</Frame>

<Steps>
  <Step title="Connected Data Sources">
    WisdomAI integrates with your data platforms (such as Snowflake, BigQuery, or Redshift), serving as the entry point for all information flowing through the system.
  </Step>

  <Step title="Semantic Modeling">
    Admins and data owners enrich the data by documenting tables, columns, and domains. They also define relationships (e.g., one-to-many, many-to-many) to create a business-friendly context for natural language understanding.
  </Step>

  <Step title="Natural Language Query (NLQ) Engine">
    Users ask questions in plain language. The NLQ engine parses these questions and translates them into SQL queries using the underlying semantic model.
  </Step>

  <Step title="Dashboard Creation">
    Responses are generated and formatted into interactive Dashboards — data-driven narratives that combine visualizations, text, and insights. These can be scheduled and shared.
  </Step>

  <Step title="Delivery and Reporting Layer">
    Dashboards and answers can be delivered via email or embedded into external applications, helping teams stay informed with minimal effort.
  </Step>

  <Step title="User Feedback and Corrections">
    Users can give feedback on dashboard accuracy, suggest corrections, or add clarifying context to improve future results.
  </Step>

  <Step title="Knowledge Updates and Review Loop">
    Admins and Data Admins review user feedback and update the semantic layer accordingly, closing the loop and continuously improving answer quality and domain understanding.
  </Step>
</Steps>

## Next steps

<CardGroup>
  <Card title="Supported Data Sources" icon="database" href="/getting-started/connect-data-sources/supported-data-sources">
    Explore the full list of databases and platforms you can connect to the system.
  </Card>

  <Card title="Connect and Test Tutorial" icon="rocket" href="/setting-up-wisdom-ai/basic-tutorial-connect-and-test">
    Walk through the initial setup to connect a data source and run your first query.
  </Card>

  <Card title="Advanced Data Modeling" icon="sitemap" href="/setting-up-wisdom-ai/advanced-data-modeling-creating-context">
    Define relationships and context in your data to enable more powerful analysis.
  </Card>

  <Card title="Provide Feedback" icon="thumbs-up" href="/setting-up-wisdom-ai/feedback-mechanisms/provide-feedback-to-the-system">
    Help improve model accuracy by rating answers and providing corrections.
  </Card>

  <Card title="Turn Answers into Dashboards" icon="book" href="/using-wisdom-ai-everyday/turn-answers-into-dashboards">
    Compile key insights and visualizations into a shareable, narrative-driven report.
  </Card>
</CardGroup>


# Overview
Source: https://docs.wisdom.ai/getting-started/overview



Welcome to the WisdomAI documentation site. These guides provide all the essential information you need to effectively utilize the platform’s features, from querying data using natural language to setting up granular access controls. Whether you are an Admin, an Explorer, or a Developer building on top of the platform, you will find detailed instructions for your role.

## Where to start?

WisdomAI caters to diverse user roles. Follow the path that aligns with your responsibilities:

<Tabs>
  <Tab title="Admins (Data Administrators)">
    **Objective**: Set up and configure WisdomAI for your organization.

    **Start Here:**

    <Columns>
      <Card title="Connect and Test" icon="1" href="/setting-up-wisdom-ai/basic-tutorial-connect-and-test" />

      <Card title="Create Context" icon="2" href="/setting-up-wisdom-ai/advanced-data-modeling-creating-context" />
    </Columns>

    **Key Actions:**

    * Connect data sources and define Domains.
    * Document tables and columns for clarity.
    * Add contextual information and reviewed queries.
    * Configure access controls and security settings.
    * Define table relationships (1:1, 1:M, M:M) to model data associations and enable efficient querying.
    * Connect your AI coding assistant to WisdomAI data using the MCP Server.
  </Tab>

  <Tab title="Explorers (Business Users)">
    **Objective:** Use WisdomAI's tools and capabilities to extract meaningful insights from your data and effectively communicate them to others.

    **Start Here:**

    <Columns>
      <Card title="Ask Better Questions" icon="1" href="/using-wisdom-ai-everyday/ask-better-questions" />

      <Card title="Turn Answers into Dashboards" icon="2" href="/using-wisdom-ai-everyday/turn-answers-into-dashboards" />

      <Card title="Share Dashboards and Set Access" icon="3" href="/using-wisdom-ai-everyday/share-dashboards-and-set-access-control" />

      <Card title="Subscribe to a Dashboard" icon="4" href="/using-wisdom-ai-everyday/schedule-dashboards-notifications" />
    </Columns>

    **Key Actions:**

    * Pose natural language questions to explore data.
    * Create and customize interactive Dashboards.
    * Share insights with team members and stakeholders.
    * Set up notifications to stay updated on key metrics.
  </Tab>

  <Tab title="Developers">
    **Objective:** Integrate WisdomAI into your product or connect it to your AI coding tools.

    **Start Here:**

    <Columns>
      <Card title="Developers Overview" icon="square-code" href="/integrations/developers" />

      <Card title="Embedding" icon="table-columns" href="/integrations/embeddings/embedding" />

      <Card title="GraphQL API" icon="code" href="/integrations/graphql-api/GraphQL-API" />

      <Card title="User Management" icon="users" href="/integrations/user-management/user-lifecycle" />
    </Columns>

    **Key Actions:**

    * Embed dashboards and chat into your web app using the iframe or React SDK.
    * Create and manage users programmatically via the GraphQL API.
    * Control data access at the user level with attributes and parameterized connections.
  </Tab>
</Tabs>

## Next steps

<CardGroup>
  <Card title="Developers" icon="code" href="/integrations/developers">
    Embed, query, and extend WisdomAI from your own stack.
  </Card>

  <Card title="Supported Data Sources" icon="database" href="/getting-started/connect-data-sources/supported-data-sources">
    Explore the full list of databases and platforms you can connect to the system.
  </Card>

  <Card title="Connect and Test Tutorial" icon="rocket" href="/setting-up-wisdom-ai/basic-tutorial-connect-and-test">
    Walk through the initial setup to connect a data source and run your first query.
  </Card>

  <Card title="Advanced Data Modeling" icon="sitemap" href="/setting-up-wisdom-ai/advanced-data-modeling-creating-context">
    Define relationships and context in your data to enable more powerful analysis.
  </Card>

  <Card title="Provide Feedback" icon="thumbs-up" href="/setting-up-wisdom-ai/feedback-mechanisms/provide-feedback-to-the-system">
    Help improve model accuracy by rating answers and providing corrections.
  </Card>

  <Card title="Turn Answers into Dashboards" icon="book-open" href="/using-wisdom-ai-everyday/turn-answers-into-dashboards">
    Compile key insights and visualizations into a shareable, narrative-driven report.
  </Card>
</CardGroup>


# Using File Attachments in Chat
Source: https://docs.wisdom.ai/improve-wisdom-ai-responses/attach-files-to-chat



You can attach a file to your WisdomAI chat to provide additional context for the session. This feature enables WisdomAI to use the information in the file to better understand and respond to your queries, serving as a temporary knowledge base throughout your conversation.

## How it works

To attach a file to your chat session, follow these steps:

1. In your chat session, click the **Upload File** icon.
2. Select your file, and ensure it is a supported file type.
3. Add your query in the chat, and click **Send**.

WisdomAI will then process the file's content and use it as a reference for your questions.

This allows for a more fluid and intuitive interaction, especially when dealing with complex data tasks. For example, you could upload a screenshot of a bar chart and ask WisdomAI to generate a similar chart using the dataset of the Domain you are using.

## Supported file types

WisdomAI currently supports a variety of file types, including images, documents, and different text formats. See the following list:

* **Images**
  * .png
  * .jpeg
  * .webp
* **Documents**
  * .pdf
* **Text Files**
  * Any file with a text/MIME type
  * .json
  * .lkml
  * .md (Markdown)
  * .log
  * .yml
  * .yaml

<Check>
  - The maximum file size you can upload is 20MB.
  - These files can also be used as data sources. To learn how to upload files to a Domain, read [**Basic Tutorial: Connect and Test > Upload CSV files**](/setting-up-wisdom-ai/basic-tutorial-connect-and-test)**.**
</Check>

## Next steps

<CardGroup>
  <Card title="Configure Domains" icon="sliders" href="/setting-up-wisdom-ai/manage-domains/understand-domains">
    Manage and customize your data domains to refine context and improve query results.
  </Card>

  <Card title="Auditing" icon="clipboard-list" href="/using-wisdom-ai-everyday/auditing">
    Organize insights by tagging chats, navigating history, and sharing vetted answers with your team.
  </Card>

  <Card title="Basic Tutorial: Connect and Test" icon="rocket" href="/setting-up-wisdom-ai/basic-tutorial-connect-and-test">
    Walk through the initial setup to connect a data source and run your first query.
  </Card>

  <Card title="Advanced Data Modeling" icon="sitemap" href="/setting-up-wisdom-ai/advanced-data-modeling-creating-context">
    Define relationships and context in your data to enable more powerful analysis.
  </Card>
</CardGroup>


# Build Dashboards
Source: https://docs.wisdom.ai/improve-wisdom-ai-responses/build-dashboards



What you may know as dashboards, in WisdomAI are called **Dashboards**. Dashboards allow you to present curated insights in a clear, structured, and visually appealing format that you can arrange and share.

<Note>
  If you are looking for help on how to turn chat answers into Dashboards, read the article [Turn Answers into Dashboards](/using-wisdom-ai-everyday/turn-answers-into-dashboards).
</Note>

This guide will walk you through the following steps after your answers are ready to be showcased, including:

* [Explore the Dashboards Editor](#explore-the-dashboards-editor)
* [Arrange Dashboard Layout](#arrange-dashboard-layout)
* [Get Stakeholders Sign-Off](#get-stakeholders-sign-off)
* [Export your Dashboard](#export-your-dashboard)

## Explore the Dashboards Editor

Once your analysis is complete and you have turned answers into cards (see the [Turn Answers into Dashboards](/using-wisdom-ai-everyday/turn-answers-into-dashboards) article), the **Dashboards** section becomes your central workspace. Here, you can refine the presentation of your insights, build out full dashboards, and prepare content for sharing.

The Dashboards Editor includes features such as:

1. A collapsible **Overview** section that includes:
   * An **Executive Summary** for setting context at the top of your Dashboard.
   * A data summary for **what's changed since** a specific date, such as yesterday, last week, etc.
2. An option to **add** a **widget**  directly from the Dashboard interface. Create **Visualization** or **Text** widgets that communicate key takeaways.
   <Info>
     The **Visualization** option opens a chat interface that helps you generate visual content based on your data. In contrast, the **Text** option opens an MDX editor to add narrative or explanatory content.
   </Info>
3. A **Filters** pane for interactive data exploration.
4. An option to **share** your Dashboard effectively.

<img alt="Dashboards Editor showing the Overview section with summary widgets and filters for refining insights" />

## Arrange Dashboard layout

Make your Dashboard both visually compelling and logically structured:

* **Move Dashboards cards around the workspace** to arrange them in order by importance, logical flow, or stakeholder preference.
* **Group related cards** to create thematic Dashboards (e.g., “Monthly Revenue Trends,” “Top Performing Reps,” “Churn Metrics”).
* [**Edit the answers to Dashboards cards**](/improve-wisdom-ai-responses/validate-and-test-answers) to emphasize key metrics and insights, ensuring your visuals match the narrative flow.

<Tip>
  A well-structured layout helps stakeholders grasp patterns faster and ask more meaningful follow-up questions.
</Tip>

All changes are saved automatically as you work. You can always return to the Dashboard later to iterate.

<img alt="Animated GIF showing how to arrange and organize cards in a Dashboard dashboard workspace" />

## Get stakeholders sign-off

Before finalizing your Dashboard for broader distribution or operational use, it is essential to obtain approval from key stakeholders. This ensures the information is accurate, aligned with business goals, and ready to guide decisions.

Here is a suggested flow:

1. [**Share the Dashboard link**](/using-wisdom-ai-everyday/share-dashboards-and-set-access-control) with stakeholders.
2. **Add context**: summarize what the Dashboard includes and the decisions it is intended to support.
3. **Collect feedback** directly within the platform or through async tools (Slack, email).
4. **Incorporate edits** based on feedback, then tag the Dashboard as final or rename it for future iterations.

<Tip>
  Keeping track of who has reviewed and approved the Dashboard helps streamline communication and build trust in the data.
</Tip>

<img alt="Example of a Dashboard ready for stakeholder sign-off with options to share and review feedback" />

## Export your Dashboard

Once you are satisfied with your layout and stakeholders have approved it, you may want to **share** it or **schedule notifications** to keep stakeholders and explorers informed. Both topics are covered in related articles.

* To learn how to share your Dashboard and manage access permissions, see the [**Share Dashboards and Set Access Control**](/using-wisdom-ai-everyday/share-dashboards-and-set-access-control) article.
  <img alt="Share options panel in a Dashboard, showing settings to manage access and sharing links" />
* If you would like to schedule Dashboard updates and receive notifications, check out the [**Schedule Dashboard Notifications**](/using-wisdom-ai-everyday/schedule-dashboards-notifications) guide.
  <img alt="Scheduling options in a Dashboard for setting automated updates and notifications" />

## Next steps

<CardGroup>
  <Card title="Turn Answers into Dashboards" icon="book-open" href="/using-wisdom-ai-everyday/turn-answers-into-dashboards">
    Compile key insights and visualizations into a shareable, narrative-driven report.
  </Card>

  <Card title="Schedule Dashboard Notifications" icon="calendar-days" href="/using-wisdom-ai-everyday/schedule-dashboards-notifications">
    Set up automated notifications to keep stakeholders updated with the latest dashboard insights.
  </Card>

  <Card title="Share Dashboards and Set Access Control" icon="share-nodes" href="/using-wisdom-ai-everyday/share-dashboards-and-set-access-control">
    Learn how to share your dashboards with others and manage who can view or edit them.
  </Card>
</CardGroup>


# Connect Unstructured Repositories or Datasets
Source: https://docs.wisdom.ai/improve-wisdom-ai-responses/connect-unstructed-repositories-datasets



WisdomAI allows you to connect your domain to an unstructured repository or dataset from an **Amazon S3 bucket**, thereby enhancing your chatbot responses and ensuring the AI understands the underlying structure of your information.

## Connect an Amazon S3 dataset

Follow the steps below to connect your Amazon S3 bucket as a data source.

1. Access your domain and, in the **Overview** tab, click **Add Data Source**.
2. In the modal that opens, select **Connect another source** from the **Data Source** selector.
3. Click **Add Data Source** to continue.

   <Frame>
     <img alt="Domain Add Data Source" />

     <img alt="Domain Add Data Source" />
   </Frame>
4. Select **Connect to Data store or MCP server**, then provide the following **Connection Details**:
   * **Connection name**
   * **Data source**: Select **Amazon S3**
5. Fill in the **Amazon S3 connection details**:
   * **Bucket Name**: The bucket where your files are stored.
   * **Authentication Method**: Choose one of the following:
     * **Access Key & Secret Key**: Provide the **Region**, **AWS Access Key ID**, and **AWS Secret Access Key**.
     * **Cross-Account Role**: Provide the **AWS Account ID** that has access to the bucket and the **AWS Role Name**.
6. Click **Select Data** to continue.
   <Frame>
     <img alt="Domain Add Data Source Select Data" />
   </Frame>
7. In the data selection screen, browse the contents of the S3 bucket and select the files or paths you want to include.
8. Confirm your selection to add the dataset as a data source.

## Next steps

<CardGroup>
  <Card title="Manage Domains" icon="sliders" href="/setting-up-wisdom-ai/manage-domains/understand-domains">
    Manage and customize your data domains to refine context and improve query results.
  </Card>

  <Card title="Auditing" icon="clipboard-list" href="/using-wisdom-ai-everyday/auditing">
    Organize insights by tagging chats, navigating history, and sharing vetted answers with your team.
  </Card>

  <Card title="Basic Tutorial: Connect and Test" icon="rocket" href="/setting-up-wisdom-ai/basic-tutorial-connect-and-test">
    Walk through the initial setup to connect a data source and run your first query.
  </Card>

  <Card title="Advanced Data Modeling" icon="sitemap" href="/setting-up-wisdom-ai/advanced-data-modeling-creating-context">
    Define relationships and context in your data to enable more powerful analysis.
  </Card>
</CardGroup>


# Enhancing Data Analysis with Custom Business Knowledge
Source: https://docs.wisdom.ai/improve-wisdom-ai-responses/enhancing-data-analysis-with-custom-business-context



WisdomAI is engineered to perform a wide range of queries directly on your dataset. If you are seeking to conduct more advanced, customized analysis, the custom business Knowledge feature allows the system to be aligned with your specific operational logic and proprietary terminology. This document outlines an example procedure for leveraging this feature to generate strategic insights.

## 1. Foundational data interrogation

The system is designed to process queries that reference explicit data points within your tables. For example, it can accurately count, group, or filter based on existing columns and values.

When a query includes business-specific terminology not explicitly defined in the dataset, such as "Strategic Account" or "At-Risk", the system, by design, will prompt for clarification. This ensures that all subsequent analysis is precise and perfectly aligned with the user's intent.

<img alt="Gif showing the first query and the answer without context" />

## 2. Implementing custom logic with business Knowledge

The Knowledge feature enables the system to execute complex queries autonomously. This is achieved by providing the tool with a set of rules that define your organization's internal logic.

As an example, let's consider that you want to empower the system to identify "At-Risk Strategic Accounts". To accomplish this, you need to provide the following definitions via the Knowledge feature:

```
1. Geographical Sales Territories: 
- NA-West (North America West): Includes [Account Names] 
_ NA-East (North America East): Includes [Account Names] 
- EMEA (Europe, Middle East, and Africa): Includes [Account Names] 

2. Account Tier Definitions: 
- A "Strategic Account" is any customer with a contract duration of 3 years or more. 
- An "At-Risk Strategic Account" is a Strategic Account where Auto Renewal is set to False. 
- A "Secure Strategic Account" is a Strategic Account where Auto Renewal is set to True.
```

<img alt="Snippet showing the Knowledge page completed with business-specific data" />

## 3. Executing multi-layered strategic analysis

With the business Knowledge supplied, the system no longer needs to prompt for clarification. It is now configured to perform the multi-layered analysis directly.

When presented with the same query:

```
Generate a list of all 'At-Risk Strategic Accounts' and show me which sales region they belong to.
```

The system executes the request. It cross-references contract duration, renewal status, and account-to-territory mapping to produce the precise, targeted list required.

This demonstrates the successful application of custom context to yield high-value, strategic business insights.

<img alt="Gif showing the same query and the answer with context" />

## 4. Granular analysis using JSON parsing Knowledge

A key challenge in data analysis is extracting information from fields containing semi-structured text. For example, a single `Skus` column might contain multiple products, tiers, and quantities in one text string, making direct calculations difficult.

The Knowledge feature resolves this by allowing users to define parsing logic with a JSON input. Without this logic, the system cannot perform calculations on data embedded within text.

The following code snippet shows an example of using JSON context \~\~was provided \~\~to teach the system how to parse the `Skus` column:

```
{
  "example_for_skus_column": {
    "comment": "Parse the 'Skus' column into a structured list.",
    "original_skus_column_value": "Sales Ultimate 15 licenses, Marketing Professional 50 users",
    "expected_parsed_structure": [
      { "product_family": "Sales", "tier": "Ultimate", "quantity": 15, "unit": "licenses" },
      { "product_family": "Marketing", "tier": "Professional", "quantity": 50, "unit": "users" }
    ]
  }
}
```

<img alt="Gif showing an example JSON Knowledge" />

With this parsing logic supplied, it is now possible to execute precise queries, like the following example:

```
What is the total quantity of 'Ultimate' tier licenses sold for the 'Sales' product line?
```

The system can now deconstruct the `Skus` field for every contract in real-time. It filters for the "Sales" product, identifies the "Ultimate" tier, extracts the corresponding quantity, and aggregates the total, providing a precise numerical answer that was previously impossible to calculate.

<img alt="A gif showing the result calculated successfully after using a JSON context to parse unstructured text" />

## Next steps

<CardGroup>
  <Card icon="sitemap" href="/setting-up-wisdom-ai/advanced-data-modeling-creating-context" title="Advanced Data Modeling">
    Define relationships and context in your data to enable more powerful analysis.
  </Card>

  <Card icon="check-double" href="/improve-wisdom-ai-responses/validate-and-test-answers" title="Validate and Test Answers">
    Understand the methods for verifying the correctness and reliability of generated answers.
  </Card>

  <Card icon="thumbs-up" href="/setting-up-wisdom-ai/feedback-mechanisms/provide-feedback-to-the-system" title="Provide Feedback to the System">
    Learn how to rate answers and provide corrections to improve the system's accuracy.
  </Card>

  <Card icon="book-open" href="/using-wisdom-ai-everyday/turn-answers-into-dashboards" title="Turn Answers into Dashboards">
    Compile key insights and visualizations into a shareable, narrative-driven report.
  </Card>
</CardGroup>


# How to Create Metrics
Source: https://docs.wisdom.ai/improve-wisdom-ai-responses/how-to-create-metrics



Metrics are numeric, quantitative values that can be measured to assess and track business performance. They help you identify trends to make informed decisions. This guide will walk you through creating and using metrics effectively in WisdomAI.

## Types of Metrics

You can have different kinds of Metrics. Here's a breakdown of the most common types:

* **Simple Metrics:** These are direct calculations from existing data. Think of something straightforward, such as the sum of your total revenue.
* **Calculated Metrics:** These metrics combine other metrics using formulas. For example, Profit could be a calculated metric derived from subtracting "Cost" from "Revenue."
* **Ratios:** Ratios involve dividing one metric by another. A classic example is Conversion Rate, calculated as "Orders" divided by "Visits."
* **Time-based Metrics:** These metrics incorporate time into their calculation, allowing you to analyze trends over periods. Examples include year-over-year growth or rolling averages.

## Create a Metric

The process of creating a metric in WisdomAI is managed within each specific Domain.

Here's a step-by-step guide:

1. Navigate to the **Metrics** Tab within a **Domain**.
   * Select the relevant **Domain** (e.g., "B2B Sales") > go to the **Context** tab > click **Metrics**.
2. Click the **Add Metric** button.

<Frame>
  <img alt="Image showing te Add Metric option" />
</Frame>

3. In the Add a Metric modal window that opens, provide your metric with a clear, concise **name** that accurately describes what it measures.
4. Input your **SQL expression** in the corresponding area.
5. Toggle the **Advanced Options** switch to access additional configurations:
   * **Associated date column:** (Optional) This allows you to specify a date column in your data that is relevant to this metric. This is particularly useful for time-based analyses, filtering by date, or for metrics that inherently track changes over time.
   * **Associated group-by columns:** (Optional) Here, you can pre-define columns that are commonly used for grouping or segmenting this metric. (e.g., account State, customer ID)
6. Once you have configured your metric, click **Save** to add it to your Domain's metrics list.

<img alt="Snippet of the Add a Metric modal showing the name, SQL expression, and Advanced options." />

## Sales Metrics examples

When you create metrics, you define the SQL expression that dictates how the metric is calculated from your raw data. This allows for precise data analysis. Once defined, they will appear in your Metrics list with their descriptions and display formats.

Here are some practical examples of sales metrics and how they might be configured.

| Metric Name             | Description                                                                                                                     | SQL Expression                                              | Display Format                   |
| :---------------------- | :------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------- | :------------------------------- |
| **Revenue**             | Total revenue before discounts and returns                                                                                      | `SUM(total_amount)`                                         | Currency (USD, 2 decimal places) |
| **Average Order Value** | Average amount spent per order                                                                                                  | `AVG(total_amount)`                                         | Currency (USD, 2 decimal places) |
| **Profit Margin**       | The percentage of revenue that is profit                                                                                        | `(SUM(total_amount) - SUM(cost)) / SUM(total_amount) * 100` | Percentage (1 decimal place)     |
| **Items Per Order**     | Average number of items in each order                                                                                           | `SUM(item_count) / COUNT(DISTINCT order_id)`                | Number (1 decimal place)         |
| **Days to Ship**        | Average time between order and shipment                                                                                         | `AVG(EXTRACT(DAY FROM ship_date - order_date))`             | Number (1 decimal place)         |
| **AverageSalesPerRep**  | Average Sales Per Rep                                                                                                           | *(Specific SQL would be defined in the system)*             | Automatic                        |
| **Total Revenue**       | Total revenue from closed-won opportunities                                                                                     | `SUM(total_amount)` *(example)*                             | Automatic                        |
| **Win\_Rate**           | Ratio of the sum of amounts for closed won opportunities to the sum of quantities for closed won and closed loss opportunities. | *(Specific SQL would be defined in the system)*             | Automatic                        |

By effectively defining and utilizing metrics within your chosen Domains, you can gain deeper insights into your operations and make data-driven decisions that propel your business forward.

## Next steps

<CardGroup>
  <Card icon="sliders" href="/setting-up-wisdom-ai/manage-domains/understand-domains" title="Manage Domains">
    Manage and customize your data domains to refine context and improve query results.
  </Card>

  <Card icon="clipboard-list" href="/using-wisdom-ai-everyday/auditing" title="Auditing">
    Organize insights by tagging chats, navigating history, and sharing vetted answers with your team.
  </Card>

  <Card icon="rocket" href="/setting-up-wisdom-ai/basic-tutorial-connect-and-test" title="Basic Tutorial: Connect and Test">
    Walk through the initial setup to connect a data source and run your first query.
  </Card>

  <Card icon="sitemap" href="/setting-up-wisdom-ai/advanced-data-modeling-creating-context" title="Advanced Data Modeling">
    Define relationships and context in your data to enable more powerful analysis.
  </Card>
</CardGroup>


# Use Evaluations Sets and Runs
Source: https://docs.wisdom.ai/improve-wisdom-ai-responses/use-evaluations-sets-and-runs



This article describes the concepts of Evaluation Sets and Evaluation Runs, which are tools used to test and validate your AI's domain performance.

## Evaluation Sets

In the Evaluation Sets tab, you can create specific sets of prompts that simulate user interactions and provide expected SQL outputs alongside these prompts. This allows for a direct comparison to see how accurately the AI converts natural language into database queries.

To create an Evaluation Set:

1. Open a Domain and click on the **Evaluation** tab.
2. Navigate to the **Evaluation Sets** Sub-tab.
3. Click **Add Evaluation**.

<img alt="Image showing the Evaluations tab" />

<img alt="Image showing the Evaluations tab" />

4. Fill out the **Create Evaluation Set** Form, providing a set **Name** and presenting a natural language query. Optionally, you can import CSV and also ground truth SQL.
5. Click on **Create Evaluation Set**. The new Evaluation set will appear listed.

<img alt="Image showing the Add Evaluations form" />

<img alt="Image showing the Add Evaluations form" />

## Evaluation Runs

Evaluation Runs are where the AI processes your defined Evaluation Sets. After running these evaluations, you can review the results to identify areas for improvement.

To run an Evaluation, go to the **Evaluations Set** tab, select an evaluation, and click on the **run icon**. You will see the results in the Evaluation Runs tab.

<img alt="Run Evaluation Pn" />

<img alt="Run Evaluation Pn" />

### Evaluation Run indicators

Evaluation Run Indicators provide a concise overview of the Run's progress and outcome. These indicators offer immediate feedback on the Evaluation's status and score, detailing how well the AI's generated responses matched the expected results. They are:

* **Status:** Signals its progress or completion.
  * Running: The evaluation run is currently in progress.
  * Completed: The evaluation run has finished successfully.
* **Score:** Reflects the result of the completed Evaluation. It tells you how many conversations passed based on the predefined **evaluation criteria** (i.e., Prompt + Expected SQL result added in the Evaluation set modal).

<Tip>
  The Score evaluation criteria refer to how much the generated answer matches the expected SQL result defined previously.
</Tip>

<img alt="Evaluation Runs Indicatorsv2 Pn" />

<img alt="Evaluation Runs Indicatorsv2 Pn" />

### Evaluation Run report

When you click the **View Report** option, you will see comprehensive details about how the evaluation run performed. Here's a breakdown of the information you'll find:

* **View Domain:** A link that allows you to navigate to the specific domain that was evaluated.
* **Soft Match:** This **Score** indicates the overall performance of the Evaluation. It shows how many of the evaluation criteria were successfully met out of the total. It is named as Soft Match since results may be considered a match even if they are not the same as the expected (provided) SQL.
* **Individual Session Details**: The report organizes the evaluation results by individual sessions or queries (e.g., Session 1, Session 2).

<img alt="View Report 01v2 Gi" />

<img alt="View Report 01v2 Gi" />

For each session, the report is broken down into several components, allowing you to analyze the AI's performance thoroughly.

* **Session Title:** This states the query or task that was evaluated for that particular session (e.g., "Calculate total revenue for closed won opportunities using ACV.").
* **Evaluation Details:** This expandable section provides specific insights into the session's outcome. The core components are detailed in the table below.

| Component            | Description                                                                                                     |
| :------------------- | :-------------------------------------------------------------------------------------------------------------- |
| **Prompt**           | The specific input prompt that was used for the session.                                                        |
| **Manual Score**     | An option for you to manually score the Evaluation (✅ or ❌), which overrides the automated score.               |
| **Automated Score**  | The system automatically assigns the score. This corresponds to the **Soft Match**.                             |
| **Ground Truth**     | The expected or correct outcome, typically the ideal SQL query (`SELECT SUM(amount) FROM Opportunity`).         |
| **Generated Result** | The output produced by the system, including the generated SQL query and the final result (e.g., `"$137.55M"`). |

<img alt="Gif showing the Session Details" />

<img alt="Gif showing the Session Details" />

<Warning>
  Providing an incorrect SQL code will lead to a syntax or semantic error. The system will display a red message detailing the nature of the error, often including the location within the query where the problem occurred, to aid in correction.

  <img alt="Example showing an Incorrect Sql in Red" />

  <img alt="Example showing an Incorrect Sql in Red" />
</Warning>

* **Conversation:** You can expand this section to review the entire conversational exchange related to that specific session. This includes:
  * **AI Workstream:** Offers a look into the AI's process, showing the tool it selected, the examples it referenced, and the step-by-step plan it followed to generate the response.
  * **Reviewed Status**: Confirms whether the response has been reviewed and summarizes the outcome (e.g., "The user received a complete response... so no further action or information is needed.").

<img alt="Show Chat V2" title="Show Chat V2" />

<img alt="Show Chat V2" title="Show Chat V2" />

Navigating the report helps you understand the system's processing, verify generated results, and review the underlying conversational logic.

## Next steps

<CardGroup>
  <Card title="Manage Domains" icon="sliders" href="/setting-up-wisdom-ai/manage-domains/understand-domains">
    Manage and customize your data domains to refine context and improve query results.
  </Card>

  <Card title="Auditing" icon="clipboard-list" href="/using-wisdom-ai-everyday/auditing">
    Organize insights by tagging chats, navigating history, and sharing vetted answers with your team.
  </Card>

  <Card title="Basic Tutorial: Connect and Test" icon="rocket" href="/setting-up-wisdom-ai/basic-tutorial-connect-and-test">
    Walk through the initial setup to connect a data source and run your first query.
  </Card>

  <Card title="Advanced Data Modeling" icon="sitemap" href="/setting-up-wisdom-ai/advanced-data-modeling-creating-context">
    Define relationships and context in your data to enable more powerful analysis.
  </Card>
</CardGroup>


# Validate and Test Answers
Source: https://docs.wisdom.ai/improve-wisdom-ai-responses/validate-and-test-answers



This guide is for Administrators responsible for ensuring the accuracy of WisdomAI responses. This workflow typically begins after an end-user [provides negative feedback on an answer](/setting-up-wisdom-ai/feedback-mechanisms/provide-feedback-to-the-system).

Here, you will learn how to edit, test, and validate responses to build confidence and improve the system's knowledge base.

## Prerequisites

* You must have **Administrator** permissions. For details, see [Access Management](/manage-account/access-management).

## 1. Edit the SQL query

When an answer is incorrect, you can directly edit the underlying SQL query.

1. Click the **Edit** button on the answer card in the chat interface.

<img alt="Chat workstream showing the edit button" />

2. The **Editor** window will open. Go to the **SQL Code** tab.
3. Modify the SQL statement to fix inaccuracies, add joins, or correct filters.
4. Click **Update response** to run the revised query and refresh the data.
5. (Optional) Switch back to the **Editor** tab to configure chart types, add filters, or drag-and-drop columns for visualization.

<img alt="Update response option" />

## 2. Test the updated answer

After editing the query, you must test the new response.

* **Retry with Adjustments:** Use the **Retry** option in the chat window to have the system regenerate the response using your new SQL.
* **Cross-Reference:** Validate the new result by cross-referencing it with a known value or an external report.
* **Test for Accuracy:** Try rephrasing the original question in a few different ways (e.g., "revenue by region" vs. "how much did each territory earn?"). If the system doesn't return the correct answer, you may need to [Add Context](#3-add-context-knowledge) to help it with precise queries.

## 3. Add Context (knowledge)

If the system consistently misunderstands terms, you can add explicit context. This helps the system formulate more precise queries.

1. Navigate to **Domains** > (Select your Domain)
2. Navigate to the **Context** tab.
3. Select the **Knowledge** tab inside the Context section.
4. Click the **+ Add Knowledge** button to begin a new entry and add natural language context. Add natural language sentences to define business terms.
   * *Example 1:* `Regions are the same as Territories.`
   * *Example 2:* `My sales stages are: Prospect, Negotiation, Closed.`
5. Click **SAVE**.

<Frame>
  <img alt="NEW Add Knowledge Steps" />
</Frame>

<Info>
  To learn more about adding context to a domain, refer to the [**Add Domain-Specific Knowledge**](/setting-up-wisdom-ai/add-domain-specific-knowledge) guide.
</Info>

## 4. Mark the answer as reviewed

Once you have confirmed the SQL is correct and the answer is accurate, save it to the system's knowledge base.

1. From the **SQL Code** tab in the **Editor** window, click **Mark as reviewed**.
2. In the **Review Question** window, add a clear title for the question (e.g., "Official Quarterly Revenue by Region").
3. Click **Confirm**.

<img alt="Review question option" />

This action saves the question and its validated SQL as a [Validated Query](/setting-up-wisdom-ai/feedback-mechanisms/reviewed-queries), which serves as a trusted reference for similar future questions.

To ensure that the information provided in the answer is accurate, relevant, and reliable, you can:

* Test and validate both natural language responses and SQL query results directly within the chat interface.
* Review the generated output by providing feedback.
* Edit or vet the SQL query when necessary.

These features help you iterate efficiently and build confidence in the outputs you receive.

<img alt="Reviewed queries are displayed" />

## Next steps

<CardGroup>
  <Card icon="clipboard-list" href="/using-wisdom-ai-everyday/auditing" title="Auditing">
    Organize insights by tagging chats, navigating history, and sharing vetted answers with your team.
  </Card>

  <Card icon="sitemap" href="/setting-up-wisdom-ai/advanced-data-modeling-creating-context" title="Advanced Data Modeling">
    Define relationships and Knowledge in your data to enable more powerful analysis.
  </Card>
</CardGroup>


# WisdomAI Docs
Source: https://docs.wisdom.ai/index



<HomeBanner />

<PageWrapper>
  <Columns>
    <HomeCard href="/getting-started/overview" title="Getting started" description="Start utilizing the platform’s features effectively" />

    <HomeCard href="/setting-up-wisdom-ai/basic-tutorial-connect-and-test" title="Setting Up WisdomAI" description="Connect data sources and start creating knowledge" />

    <HomeCard href="/improve-wisdom-ai-responses/enhancing-data-analysis-with-custom-business-context" title="Improve WisdomAI Responses" description="Explore the available tools to enhance your responses" />
  </Columns>

  <Columns>
    <HomeCard href="/using-wisdom-ai-everyday/ask-better-questions" title="Using WisdomAI Everyday" description="Craft effective queries to get the best possible information" />

    <HomeCard href="/integrations/developers" title="Developers" description="Embed, query, and extend WisdomAI from your own stack." />

    <HomeCard href="/product-updates/july-2026/july-features" title="Product Updates" description="Stay up-to-date with the latest features and improvements" />
  </Columns>
</PageWrapper>

<McpBanner />


# Slack
Source: https://docs.wisdom.ai/integrations/connect-to-slack



Integrate WisdomAI with your Slack workspace to query your business data directly from your channels and direct messages. This allows you to get insights without switching contexts.

## Before you begin

Make sure you have the following:

* An active WisdomAI account.
* Administrative permissions to install apps in your Slack workspace.

## Connect to your Slack workspace

Follow these steps to connect your WisdomAI account to Slack:

1. In the left-hand navigation of WisdomAI, click the **Settings** icon, then select **Slack Integration**. You can also navigate directly to `https://<your-account>.askwisdom.ai/settings/slack`, replacing `<your-account>` with your account name.
   <Frame>
     <img alt="Image" />
   </Frame>
2. The **Slack Integration** page introduces what the WisdomAI Slack app can do. Click **Connect to Slack** to start the install.
   <Frame>
     <img alt="Image" />
   </Frame>
3. Authorize the application on the Slack page you are redirected to. After reviewing the permissions WisdomAI is requesting, click **Allow** to grant access and install the app in your workspace.
   <Frame>
     <img alt="Image" />
   </Frame>
4. After authorization, you are returned to the **Slack Integration** page. The page now shows that the WisdomAI app is connected to your Slack workspace, with a green **Connected** indicator.
   <Frame>
     <img alt="Image" />
   </Frame>
5. Look for the **@WisdomAI** app in your Slack workspace and start using it. When you open a direct message with the app, you'll see a welcome message and some suggested questions. You can now ask questions in natural language to get insights from your data directly within Slack.
   <Frame>
     <img alt="WisdomAI app welcome message in Slack" />
   </Frame>

## Disconnect the Slack app

To disconnect the WisdomAI app from your Slack workspace:

1. Open **Settings** > **Slack Integration**.
2. Click the **Connected** chip in the upper right of the connection card.
3. Select **Disconnect Slack workspace** from the menu.
4. In the confirmation dialog, click **Disconnect**.

<Frame>
  <img alt="Image" />
</Frame>

<Note>
  Disconnecting does not uninstall the app from your Slack workspace. The app stops responding to questions and scheduled Slack notifications stop working until you reconnect.
</Note>

## Permissions

When you connect WisdomAI to Slack, you will be asked to grant a set of permissions. These allow the WisdomAI app to receive your questions and post answers back into your workspace.

Here is a detailed breakdown of what each permission allows WisdomAI to do:

| Permission          | Description                                                                                                        |
| :------------------ | :----------------------------------------------------------------------------------------------------------------- |
| `app_mentions:read` | Allows the app to see messages that directly mention `@WisdomAI` in conversations where the app is in.             |
| `assistant:write`   | Allows WisdomAI to act as an AI Assistant, enabling it to provide intelligent responses and analysis within Slack. |
| `channels:history`  | View messages and content in public channels that WisdomAI has been added to.                                      |
| `chat:write`        | Allows WisdomAI to send messages and answers to your questions in channels and conversations.                      |
| `chat:write.public` | Allows WisdomAI to send messages to public channels that it isn't a member of.                                     |
| `files:write`       | Allows WisdomAI to upload, edit, and delete files.                                                                 |
| `im:history`        | View messages and content in direct messages with the WisdomAI app.                                                |
| `reactions:write`   | Allows WisdomAI to add emoji reactions to messages, for example, to acknowledge a command.                         |
| `users:read`        | Allows WisdomAI to view basic information about users in your workspace, such as their names and user IDs.         |
| `users:read.email`  | View email addresses of people in the workspace.                                                                   |

## Query your data in Slack

After connecting the app, you can interact with WisdomAI directly from your Slack workspace.

1. **Ask a Question**: You can start a direct message with the WisdomAI app or mention it in a channel to ask a question in natural language. The app will confirm that it is processing your request.
2. **Receive an Answer**: WisdomAI delivers an interactive response directly in Slack. A typical answer includes:
   * A chart visualizing the data, such as a bar chart of AWS usage by service.
   * A set of suggested follow-up questions to guide your analysis.
   * Buttons to **Show data**, **Show SQL**, change the chart type, or **Export CSV**.
     <img alt="Snippet showing questions and answers in Slack" title="Snippet showing questions and answers in Slack" />
3. **Interact with Results**: You can modify the visualization and explore the data without leaving Slack. For example, you can change the chart to an Area chart or expand the data table to see the specific values for each service.  See the example below: <img alt="Slack Example Pn" /> You can also select **View in WisdomAI** to continue your analysis in the main web application.

## Next steps

<CardGroup>
  <Card title="Embed Chat" icon="message" href="/integrations/embeddings/iframe/embed-chat">
    Discover how to embed conversational AI chat interfaces
  </Card>

  <Card title="Embed a Dashboard" icon="chart-bar" href="/integrations/embeddings/iframe/embed-a-dashboard">
    Learn how to embed interactive dashboards and visualizations
  </Card>

  <Card title="Impersonate User API" icon="user" href="/integrations/graphql-api/mutations/auth/impersonate-user">
    Detailed documentation for the authentication API
  </Card>
</CardGroup>


# Developers
Source: https://docs.wisdom.ai/integrations/developers



WisdomAI gives your team several ways to build on top of the platform. Whether you're embedding analytics into a product, managing users programmatically, or connecting WisdomAI to your AI toolchain, this section covers everything you need.

<CardGroup>
  <Card title="Embedding" icon="table-columns" href="/integrations/embeddings/embedding">
    Embed WisdomAI dashboards and chat into your product using the iframe or SDK paths. Manage users, attributes, and sessions programmatically.
  </Card>

  <Card title="GraphQL API" icon="code" href="/integrations/graphql-api/GraphQL-API">
    Reference for all mutations, queries, objects, and subscriptions.
  </Card>
</CardGroup>

## Choose your path

If you're not sure where to start, pick the question that fits your goal.

<AccordionGroup>
  <Accordion title="I want to embed a WisdomAI dashboard or chat inside my web app.">
    Use the [Embedding](/integrations/embeddings/embedding) path. Start with the [iframe overview](/integrations/embeddings/embedding-modes) for a quick integration, or the [SDK](/integrations/embeddings/sdk/sdk-overview) for a native React component approach.
  </Accordion>

  <Accordion title="I want to create and manage users from my backend.">
    Use the [GraphQL API](/integrations/graphql-api/GraphQL-API). The [User Management](/integrations/user-management/user-lifecycle) section covers `createUsers`, `setUserAttributes`, `impersonateUser`, and related mutations with cURL examples.
  </Accordion>

  <Accordion title="I want to control what data each user can access.">
    Read [User Attributes](/integrations/user-management/user-attributes) first. Attributes are the mechanism behind parameterized connections and row-level authorization.
  </Accordion>
</AccordionGroup>

## Before you start

Here are a few things that apply across all integration paths.

* All paths require a bearer token. Each section covers how to obtain one.
* Your base URL for all API calls is `https://<your-tenant>.wisdom.ai/graphql`. Use the same domain you use to log in to WisdomAI.

<Note>
  Both `wisdom.ai` and `askwisdom.ai` are valid tenant domains depending on your deployment. If you see a `getaddrinfo ENOTFOUND` error, confirm your tenant URL with your WisdomAI account team.
</Note>

## Start building

<CardGroup>
  <Card title="Embedding overview" icon="table-columns" href="/integrations/embeddings/embedding">
    Start here if you're integrating WisdomAI into a product.
  </Card>

  <Card title="SDK Quickstart" icon="rocket" href="/integrations/embeddings/sdk/sdk-quickstart">
    Install, wire up auth, and render your first dashboard.
  </Card>

  <Card title="User Management" icon="users" href="/integrations/user-management/user-lifecycle">
    Create users, set attributes, and manage workspace access via API.
  </Card>
</CardGroup>


# Overview
Source: https://docs.wisdom.ai/integrations/embeddings/embedding



Embed a streamlined, white-label version of WisdomAI's chat and dashboards directly into your application.

Embedded pages intentionally omit WisdomAI branding and navigation. All core capabilities (natural-language Q\&A, table generation, and chart rendering) remain intact.

The section below describes the steps to configure and test your embedded chat and dashboards.

<Note>
  All API and embed URL examples use `{ACCOUNT}.wisdom.ai` as a placeholder. Replace it with the base URL of your WisdomAI tenant — the same domain you use to log in. Both `wisdom.ai` and `askwisdom.ai` are valid depending on your deployment.
</Note>

## Before start

This overview walks through iframe embedding, the fastest path to a working embed. Depending on your use case, you may also want to reference:

<CardGroup>
  <Card title="GraphQL API" icon="code" href="/integrations/graphql-api/GraphQL-API">
    Build a fully custom, API-based integration. Covers authentication, mutations, queries, and error handling for developers who need more control than an iframe provides.
  </Card>

  <Card title="User Management" icon="users" href="/integrations/user-management/user-lifecycle">
    Create and manage end users on the WisdomAI platform, including role assignment, user attributes, and impersonation. Applies to every integration path.
  </Card>
</CardGroup>

User management is shared across all integration paths: whether you embed via iframe, call the GraphQL API directly, or use the SDK, end users must first be provisioned in WisdomAI before they can be impersonated into a session.

## Embedding flow

Every embedded session follows this five-step flow:

<Steps>
  <Step title="Get your access token">
    Contact `support@wisdom.ai` to receive your Access Key. This is a permanent credential, not a JWT or session token. It authenticates your server to the WisdomAI API and grants impersonation permissions. It does not expire and must be kept secret.
  </Step>

  <Step title="Get your access token">
    Every WisdomAI user can create and manage their own API keys. To obtain your dedicated access key, follow the steps in [this article](/settings/api-keys).

    This is a permanent credential, not a JWT or session token. It authenticates your server to the WisdomAI API and grants impersonation permissions.

    <Warning>
      Never expose your access key in client-side code. It provides long-term impersonation capabilities and must be kept secret. Store it only in secure server-side environment variables or a secret management system. If compromised, an attacker could impersonate any user in your organization.
    </Warning>
  </Step>

  <Step title="Create the end user">
    Call `createUsers` to provision the user in WisdomAI:

    <Note>
      **Authentication:** This management mutation requires a valid Bearer JWT with `iam:write` permissions. Typically, your backend obtains this by exchanging your Access Key via your auth system.
    </Note>

    Example Request:

    ```bash theme={null}
    curl -s -X POST \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $JWT" \
      -d '{
        "query": "mutation CreateUsers($input: CreateUsersInput!) { createUsers(input: $input) { status { code message } } }",
        "variables": {
          "input": {
            "emails": ["alice@yourcompany.com"],
            "workspaceID": "{{WORKSPACE_ID}}",
            "roleAssignments": [{ "roleId": "00000000-0000-0000-0000-000000000003", "scopes": ["{{DOMAIN_ID}}"] }],
            "sendWelcomeEmail": false
          }
        }
      }' \
      https://{ACCOUNT}.wisdom.ai/graphql
    ```

    <Note>
      **Key considerations:**

      * **Email uniqueness:** User matching is email-based. If your users share emails across tenants, append a unique identifier (e.g., `alice+123@company.com`) to the email prefix to prevent session collisions.
      * **Role overwrites:** If a user already exists, `createUsers` succeeds but re-applies the provided roles, overwriting manual changes. Use `listUsers` to check status first if you wish to avoid resets.
    </Note>
  </Step>

  <Step title="Set user attributes (optional)">
    User attributes are key-value pairs used for row-level authorization and personalized data access.

    * **Sources:** Attributes can be stored in the Wisdom **DATABASE** (via API) or derived from **JWT** SSO claims (read-only).
    * **Creation/Update:** Set them at creation time via `userAttributes` in `CreateUsersInput`, or update them later via `setUserAttributes`.

    <Warning>
      The `setUserAttributes` mutation replaces **all** DATABASE-sourced attributes for that user. You must provide the complete set of attributes you wish to persist, not just the changes.
    </Warning>

    See [User Attributes](/integrations/user-management/user-attributes) for details on how attributes work and how to set them.
  </Step>

  <Step title="Impersonate the user to get a JWT">
    Call `impersonateUser` from your server to generate a 1-hour JWT for the user. This mutation is a public API member that uses your permanent Descope Access Key as an argument (`accessToken`) rather than a standard Authorization header. This step must always be performed server-side.

    <Warning>
      Never expose your permanent access token in client-side code. It provides long-term impersonation capabilities and must be protected on your backend. If compromised, an attacker could impersonate any user in your organization. Store it only in secure server-side environment variables or a secret management system.
    </Warning>

    Example Request:

    ```bash theme={null}
    curl -s -X POST \
      -H "Content-Type: application/json" \
      -d '{
        "query": "mutation ImpersonateUser($accessToken: String!, $userEmail: String!) { impersonateUser(accessToken: $accessToken, userEmail: $userEmail) }",
        "variables": {
          "accessToken": "<your_permanent_access_token>",
          "userEmail": "alice@yourcompany.com"
        }
      }' \
      https://{ACCOUNT}.wisdom.ai/graphql
    ```

    The API responds with a JWT that authenticates as the impersonated user. This token expires in **1 hour**. WisdomAI will notify your page via a `postMessage` event when the token is about to expire. See [Session Management](/integrations/embeddings/session-management) for the full refresh flow.

    See [Impersonate User](/integrations/graphql-api/mutations/auth/impersonate-user) for the full API reference, including information on passing transient attributes.
  </Step>

  <Step title="Impersonate the user to get a JWT">
    Call `impersonateUser` from your server to generate a 1-hour JWT for the user. This mutation is a public API member that uses your permanent Descope Access Key as an argument (`accessToken`) rather than a standard Authorization header. This step must always be performed server-side.

    Example Request:

    ```bash theme={null}
    curl -s -X POST \
      -H "Content-Type: application/json" \
      -d '{
        "query": "mutation ImpersonateUser($accessToken: String!, $userEmail: String!) { impersonateUser(accessToken: $accessToken, userEmail: $userEmail) }",
        "variables": {
          "accessToken": "<your_permanent_access_token>",
          "userEmail": "alice@yourcompany.com"
        }
      }' \
      https://{ACCOUNT}.wisdom.ai/graphql
    ```

    The API responds with a JWT that authenticates as the impersonated user. This token expires in **1 hour**. WisdomAI will notify your page via a `postMessage` event when the token is about to expire. See [Session Management](/integrations/embeddings/session-management) for the full refresh flow.

    See [Impersonate User](/integrations/graphql-api/mutations/auth/impersonate-user) for the full API reference, including information on passing transient attributes.
  </Step>

  <Step title="Use the JWT in the embed URL">
    Append the JWT as a `token` query parameter to the embed URL and set it as the `src` of your embed.

    <Note>
      If your embed uses voice input or camera features, add `allow="microphone; camera"` to the `<iframe>` tag.
    </Note>

    The following examples show how to use each embed path with an `<iframe>`, but the same URL structure applies regardless of your integration method.

    ```html theme={null}
    <!-- Full-app embed (search + dashboards + chat) -->
    <iframe
      src="https://{ACCOUNT}.wisdom.ai/embed/search?token=<JWT>"
      style="width: 100%; height: 100%; border: 0;" />

    <!-- Dashboards list view -->
    <iframe
      src="https://{ACCOUNT}.wisdom.ai/embed/dashboards?token=<JWT>"
      style="width: 100%; height: 100%; border: 0;" />

    <!-- Embed a specific dashboard -->
    <iframe
      src="https://{ACCOUNT}.wisdom.ai/embed/dashboards/<id>?token=<JWT>"
      style="width: 100%; height: 100%; border: 0;" />

    <!-- Embed a specific chat -->
    <iframe
      src="https://{ACCOUNT}.wisdom.ai/embed/chat/<conversationId>?token=<JWT>"
      style="width: 100%; height: 100%; border: 0;" />
    ```
  </Step>

  <Step title="Use the JWT in the embed URL">
    Append the JWT as a `token` query parameter to the embed URL and set it as the `src` of your embed.

    <Note>
      If your embed uses voice input, camera, or clipboard features, add `allow="microphone; camera; clipboard-write"` to the `<iframe>` tag.
    </Note>

    The following examples show how to use each embed path with an `<iframe>`, but the same URL structure applies regardless of your integration method.

    ```html theme={null}
    <!-- Full-app embed (search + dashboards + chat) -->
    <iframe
      src="https://{ACCOUNT}.wisdom.ai/embed/search?token=<JWT>"
      style="width: 100%; height: 100%; border: 0;" />

    <!-- Dashboards list view -->
    <iframe
      src="https://{ACCOUNT}.wisdom.ai/embed/dashboards?token=<JWT>"
      style="width: 100%; height: 100%; border: 0;" />

    <!-- Embed a specific dashboard -->
    <iframe
      src="https://{ACCOUNT}.wisdom.ai/embed/dashboards/<id>?token=<JWT>"
      style="width: 100%; height: 100%; border: 0;" />

    <!-- Embed a specific chat -->
    <iframe
      src="https://{ACCOUNT}.wisdom.ai/embed/chat/<conversationId>?token=<JWT>"
      style="width: 100%; height: 100%; border: 0;" />
    ```
  </Step>
</Steps>

## Manage the session

Once the initial iframe is rendered, you must manage the session lifecycle to prevent user timeouts or "sticky" sessions when switching users. Read [Session Management](/integrations/embeddings/session-management) for best practices on handling token expiry, refreshing tokens without reloading the page, and switching between users.

## Related articles

<CardGroup>
  <Card title="Embed a Chat" icon="message" href="/integrations/embeddings/iframe/embed-chat">
    Embed the conversational AI chat interface
  </Card>

  <Card title="Embed a Dashboard" icon="chart-bar" href="/integrations/embeddings/iframe/embed-a-dashboard">
    Embed interactive dashboards and visualizations
  </Card>

  <Card title="Impersonate User API" icon="user-secret" href="/integrations/graphql-api/mutations/auth/impersonate-user">
    Full reference for the impersonation mutation
  </Card>

  <Card title="Create Users API" icon="user-plus" href="/integrations/graphql-api/mutations/user/create-users">
    Full reference for user provisioning
  </Card>

  <Card title="GraphQL Primer" icon="code" href="/integrations/graphql-api/graphql-primer">
    New to GraphQL? Start here
  </Card>

  <Card title="Embedding Modes" icon="list-alt" href="/integrations/embeddings/embedding-modes">
    All supported embed paths and iframe requirements
  </Card>
</CardGroup>


# Embedding Modes
Source: https://docs.wisdom.ai/integrations/embeddings/embedding-modes



WisdomAI supports four embed paths. Each path renders a different slice of the WisdomAI interface inside your iframe. All paths require a valid JWT passed as the `token` query parameter.

<Note>
  Replace `{ACCOUNT}.wisdom.ai` with the base URL of your WisdomAI tenant — the same domain you use to log in. Both `wisdom.ai` and `askwisdom.ai` are valid depending on your deployment.
</Note>

## Supported paths

The paths below map to different parts of the WisdomAI interface. Use the one that matches what you want to expose to your embedded users.

### Full-app embed

`/embed/search` renders the full WisdomAI interface: search, dashboards, and chat in a single view.

```html theme={null}
<iframe
  src="https://{ACCOUNT}.wisdom.ai/embed/search?token=<JWT>"
  allow="microphone; camera; clipboard-write"
  style="width: 100%; height: 100%; border: 0;"
></iframe>
```

### Dashboards list view

`/embed/dashboards` renders the list of all dashboards the impersonated user has access to.

```html theme={null}
<iframe
  src="https://{ACCOUNT}.wisdom.ai/embed/dashboards?token=<JWT>"
  allow="microphone; camera; clipboard-write"
  style="width: 100%; height: 100%; border: 0;"
></iframe>
```

### Specific dashboard

`/embed/dashboards/[id]` renders a single dashboard by ID.

```html theme={null}
<iframe
  src="https://{ACCOUNT}.wisdom.ai/embed/dashboards/<id>?token=<JWT>"
  allow="microphone; camera; clipboard-write"
  style="width: 100%; height: 100%; border: 0;"
></iframe>
```

### Specific chat

`/embed/chat/[conversationId]` renders a specific chat conversation. You can optionally pass a `messageid` parameter to automatically scroll to a specific response.

```html theme={null}
<iframe
  src="https://{ACCOUNT}.wisdom.ai/embed/chat/<conversationId>?token=<JWT>&messageid=<messageId>"
  allow="microphone; camera; clipboard-write"
  style="width: 100%; height: 100%; border: 0;"
></iframe>
```

## iframe requirements

All embed paths require the `allow="microphone; camera; clipboard-write"` attribute on the iframe element. Omitting it disables voice input, camera, and clipboard features within the embedded interface.

## Related articles

<CardGroup>
  <Card title="Embedding Overview" icon="code" href="/integrations/embeddings/embedding">
    Full server-side embedding flow including authentication
  </Card>

  <Card title="Embed a Dashboard" icon="chart-bar" href="/integrations/embeddings/iframe/embed-a-dashboard">
    Step-by-step guide for embedding a specific dashboard
  </Card>

  <Card title="Embed Chat" icon="message" href="/integrations/embeddings/iframe/embed-chat">
    Step-by-step guide for embedding a chat interface
  </Card>

  <Card title="Session Management" icon="clock" href="/integrations/embeddings/session-management">
    Token expiry, refresh flow, and switching users
  </Card>
</CardGroup>


# Error Handling
Source: https://docs.wisdom.ai/integrations/embeddings/error-handling



The WisdomAI GraphQL API always returns HTTP 200, even when a request fails. You must inspect the response body to determine whether an operation succeeded.

## HTTP 200 on failure

Do not use the HTTP status code to detect errors. A failed GraphQL response returns HTTP 200 with either an `errors` array (for request-level failures) or a `status` object with a non-OK `code` (for mutation-level failures).

**Request-level error (HTTP 200)**

```json theme={null}
{
  "errors": [
    {
      "message": "Unauthorized",
      "locations": [{ "line": 1, "column": 1 }]
    }
  ],
  "data": null
}
```

**Mutation failure (HTTP 200)**

```json theme={null}
{
  "data": {
    "createUsers": {
      "status": {
        "code": "ERROR",
        "message": "User with email already exists"
      }
    }
  }
}
```

## Mutation response status

Mutations that affect users or resources return a `ResponseStatus` object:

```graphql theme={null}
type ResponseStatus {
  code: StatusCode!
  message: String!
}

enum StatusCode {
  NONE
  OK
  ERROR
  NOT_FOUND
}
```

Always request `status { code message }` in your mutation selection set:

```graphql theme={null}
mutation CreateUsers($input: CreateUsersInput!) {
  createUsers(input: $input) {
    status {
      code
      message
    }
  }
}
```

| Code        | Meaning                                      |
| ----------- | -------------------------------------------- |
| `OK`        | Operation succeeded                          |
| `ERROR`     | Operation failed (see `message` for details) |
| `NOT_FOUND` | The requested resource does not exist        |
| `NONE`      | No status available                          |

## Transport-level HTTP errors

HTTP errors other than 200 indicate a transport or authentication problem, not an application failure:

| HTTP status | Message               | Cause                                   |
| ----------- | --------------------- | --------------------------------------- |
| `401`       | Unauthorized          | Invalid or missing authentication token |
| `400`       | Bad Request           | Malformed request payload               |
| `500`       | Internal Server Error | Unexpected API failure                  |

<Note>
  All application-level errors and mutation failures return **HTTP 200 OK**. Refer to the response body for error details.
</Note>

## Related articles

<CardGroup>
  <Card title="GraphQL API" icon="code" href="/integrations/graphql-api/GraphQL-API">
    Authentication and endpoint reference
  </Card>

  <Card title="ResponseStatus" icon="circle-info" href="/integrations/graphql-api/objects/response-status">
    Full reference for the ResponseStatus object
  </Card>
</CardGroup>


# Embed a Dashboard
Source: https://docs.wisdom.ai/integrations/embeddings/iframe/embed-a-dashboard



This guide outlines the process for embedding a WisdomAI Dashboard into your application. Before proceeding, make sure you've reviewed the [Embeddings Overview](/integrations/embeddings/embedding) for authentication setup and security requirements.

<Note>
  The API and embed URL examples use `<customer>.wisdom.ai` as a placeholder. Replace it with the base URL of your WisdomAI tenant — the same domain you use to log in. Both `wisdom.ai` and `askwisdom.ai` are valid depending on your deployment.
</Note>

## Construct the embed URL

Construct the special embed URL for your Dashboard and append the newly generated JWT in the authentication stage.

1. Take your original Dashboard URL and insert `/embed/` before the Dashboard's name and ID.
2. Append the JWT as a `token` query parameter. The URL should look like the following:
   * **Original URL**: `https://<customer>.wisdom.ai/dashboards/name-id`
   * **Final Embed URL**: `https://<customer>.wisdom.ai/dashboards/embed/name-id?token=<JWT_FROM_STEP_1>`
3. You can now use this URL as the `src` for an `<iframe>` in your application:
   ```html theme={null}
   <iframe
     src="https://<customer>.wisdom.ai/dashboards/embed/name-id?token=<JWT_TOKEN>"
     style="width: 100%; height: 100%; border: 0;" />
   ```

<Note>
  **URL Update: Story to Dashboard**

  The embedding URL has been updated to use `/dashboards/` instead of `/stories/`.

  If you are currently using an older URL containing `/stories/`, it will continue to work and does not require immediate replacement.
</Note>

## Controlling edit permissions with RBAC

Embedded dashboards reflect the user's RBAC role. To hide edit buttons and prevent modifications in your embedded view, assign the user the **Viewer** role when creating them. There is no separate embed-specific parameter for this.

See [RBAC for Embedded Users](/integrations/user-management/rbac) for instructions on assigning roles and a full breakdown of what each role controls in the embedded interface.

## Validation

To validate that the process worked, open the final embed URL in your browser. The WisdomAI Dashboard should load correctly without prompting for a login. If you encounter an error, please refer to the troubleshooting steps below.

## Next steps

<CardGroup>
  <Card title="Embed Chat" icon="message" href="/integrations/embeddings/iframe/embed-chat">
    Discover how to embed conversational AI chat interfaces
  </Card>

  <Card title="Impersonate User API" icon="user" href="/integrations/graphql-api/mutations/auth/impersonate-user">
    Detailed documentation for the authentication API
  </Card>
</CardGroup>


# Embed a Chat
Source: https://docs.wisdom.ai/integrations/embeddings/iframe/embed-chat



Embed a streamlined, white-label version of WisdomAI Chat directly into your application.

<Info>
  The embedded chat UI is hosted at: `https://<customer>.wisdom.ai/chat/embed`
</Info>

This guide outlines the process for embedding WisdomAI Chat into your application. Before proceeding, ensure you've reviewed the [Embeddings Overview](/integrations/embeddings/embedding) for authentication setup and security requirements.

<Note>
  The API and embed URL examples use `<customer>.wisdom.ai` as a placeholder. Replace it with the base URL of your WisdomAI tenant — the same domain you use to log in. Both `wisdom.ai` and `askwisdom.ai` are valid depending on your deployment.
</Note>

## Embed the WisdomAI Chat in your application

To embed the chat into your application, add the iframe shown below.

```html theme={null}
<iframe
  src="https://<customer>.wisdom.ai/chat/embed?token=<signed-jwt>"
  style="width: 100%; height: 100%; border: 0;" />
```

In the token query param, add the signed `jwt-token` that you generated in the authentication stage. Each embedded chat session will automatically create a new conversation.

The embedded page controls the chat experience; no further state management is required after the initial load.

## Next steps

<CardGroup>
  <Card title="Embed a Dashboard" icon="chart-bar" href="/integrations/embeddings/iframe/embed-a-dashboard">
    Learn how to embed interactive dashboards and visualizations
  </Card>

  <Card title="Impersonate User API" icon="user" href="/integrations/graphql-api/mutations/auth/impersonate-user">
    Detailed documentation for the authentication API
  </Card>
</CardGroup>


# Authentication
Source: https://docs.wisdom.ai/integrations/embeddings/sdk/sdk-auth



The SDK uses a two-package auth model: `@wisdomai/node` runs on your backend and mints short-lived tokens; `WisdomProvider` runs in the browser and consumes them. Your long-lived access token never reaches the browser.

## How it works

Your long-lived access token is a secret and must **never** reach the browser. The flow is:

```mermaid theme={null}
sequenceDiagram
  participant Browser as Your React app
  participant Backend as Your backend
  participant Wisdom as WisdomAI API
  Browser->>Backend: POST /auth-token
  Backend->>Wisdom: exchange access token (via @wisdomai/node)
  Wisdom-->>Backend: short-lived JWT
  Backend-->>Browser: { jwt, baseUrl }
  Browser->>Wisdom: load dashboard data with JWT
```

1. Your **backend** holds the access token and uses `@wisdomai/node` to exchange it for a short-lived JWT.
2. Your **frontend** calls a same-origin endpoint (e.g. `POST /auth-token`) to fetch that JWT.
3. `WisdomProvider` fetches the JWT on load and **refreshes it before it expires** — you don't manage token lifecycle yourself.

## Backend: exchange the token (`@wisdomai/node`)

Construct a `WisdomAI` client with your access token and base URL, then call `getAuthToken()` to mint a short-lived JWT. It returns `{ jwt, baseUrl }`, which is exactly the shape the frontend provider expects.

```jsx theme={null}
import { WisdomAI } from '@wisdomai/node';
const wisdom = new WisdomAI({
  accessToken: process.env.WISDOM_ACCESS_TOKEN, // server-side secret
  baseUrl: process.env.WISDOM_BASE_URL,         // https://your-org.wisdom.ai
});
// inside your route handler:
const token = await wisdom.getAuthToken(); // -> { jwt, baseUrl }
```

<Tip>
  See [Quickstart](/integrations/embeddings/sdk/sdk-quickstart) for the full express endpoint example.
</Tip>

## Frontend: `WisdomProvider`

By default, `WisdomProvider` fetches the token from a same-origin `POST /auth-token` and refreshes it before expiry. To point it elsewhere (or add headers/credentials), pass your own `getAuthToken`:

```tsx theme={null}
<WisdomProvider
  getAuthToken={async () => {
    const res = await fetch('/auth-token', { method: 'POST' });
    return res.json(); // must resolve to { jwt, baseUrl }
  }}
  theme={/* ... */}
>
  {/* dashboards, widgets */}
</WisdomProvider>
```

## Multi-tenant data isolation

If you serve multiple customers (or want each end user to see only their own data), have your backend issue a **per-user** JWT when exchanging the token. Wisdom applies row-level security based on that user identity, so each viewer only sees the rows they're entitled to, without you building separate dashboards per tenant.

## Token lifecycle

Embedded JWTs are short-lived (about one hour) and the provider refreshes them automatically. For the full refresh mechanics and how switching users works, see [Session Management](/integrations/embeddings/session-management).

## Next steps

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/integrations/embeddings/sdk/sdk-quickstart">
    Set up the SDK and embed your first dashboard in minutes.
  </Card>

  <Card title="Components" icon="react" href="/integrations/embeddings/sdk/sdk-components">
    Browse the React components available for embed a full dashboard, composable widgets, and filters.
  </Card>
</CardGroup>


# Components
Source: https://docs.wisdom.ai/integrations/embeddings/sdk/sdk-components



The `@wisdomai/react` package gives you several ways to embed analytics, from a whole dashboard down to a single visualization you wrap in your own card. All of them live inside a `WisdomProvider` (see [Quickstart](/integrations/embeddings/sdk/sdk-quickstart)).

This page covers the following components:

* [Embed a full dashboard](#embed-a-full-dashboard)
* [Chat](#chat)
* [DashChat](#dashchat)
* [Embed a single widget](#embed-a-single-widget)
* [Composable widgets (advanced)](#composable-widgets-advanced)
* [Filters](#filters)

## Embed a full dashboard

The `<Dashboard>` component renders an entire Wisdom dashboard, including the header, filter bar, and widget grid:

```tsx theme={null}
import { WisdomProvider, Dashboard } from '@wisdomai/react';
 
<WisdomProvider theme={/* ... */}>
  <Dashboard dashboardId="<your-dashboard-id>" />
</WisdomProvider>
```

## Chat

Embed a conversation surface: viewers ask questions in natural language and answers stream back as charts, tables, and narratives, each in a titled card. Chat does not require a dashboard, wrap the conversation components in `ConversationProvider`:

```tsx theme={null}
import {
  WisdomProvider,
  ConversationProvider,
  Conversation,
  ConversationMessages,
  useConversation,
} from '@wisdomai/react';

function Chat() {
  const { submit, messages, user } = useConversation();
  return (
    <Conversation onSubmit={submit}>
      <ConversationMessages messages={messages} user={user} />
    </Conversation>
  );
}

<WisdomProvider theme={/* ... */}>
  <ConversationProvider>
    <Chat />
  </ConversationProvider>
</WisdomProvider>
```

What viewers get:

* Streamed answers as they are generated, with charts, tables, and narratives rendered as titled cards in the thread.
* An inline clarification form when more detail is needed to answer, instead of a guess.
* Suggested follow-up questions, message timestamps, and an explicit error row when a message fails.
* A "Show data" toggle that reveals the table behind an answer chart, and an "Export as…" menu for saving a chart as an image.

The conversation is created on the first submitted question. On its own, Chat has no domain preselected: set one from your own UI via `setDomainId` (returned by `useConversation()`). Inside a dashboard the domain comes from the dashboard automatically, that is DashChat, below.

Building blocks: `ConversationProvider`, `Conversation`, `ConversationInput`, `ConversationMessages`, `ClarificationForm`, the `useConversation` / `useConversationChat` hooks, and `ConversationsAPI` for programmatic create/send.

## DashChat

DashChat is Chat attached to a dashboard: a side panel scoped to the dashboard's own domains, so viewers ask follow-up questions about the same data the widgets are built on. One prop turns it on:

```tsx theme={null}
import { WisdomProvider, Dashboard } from '@wisdomai/react';
 
<WisdomProvider theme={/* ... */}>
  <Dashboard dashboardId="<your-dashboard-id>" showDashboardChat height="100vh" />
</WisdomProvider>
```

* The panel selects a domain from the dashboard's own domains, so answers come from the same governed data as the widgets. (`DashboardDomainSelector` renders the matching domain picker.)
* The dashboard and the panel split the width proportionally, and the panel has a show/hide toggle. Pass `height` (a number is pixels, `"100vh"` fills the viewport) so the widgets grid and the panel scroll independently while the header and filters stay pinned.
* Every widget gains an **Ask a follow-up question** action in its menu, which pre-fills the chat input with a question about that widget.

<Note>
  Chat and DashChat ship in `@wisdomai/react@0.0.12`, currently published on the `latest` npm tag: `npm install @wisdomai/react@latest`.
</Note>

## Embed a single widget

Prefer to place one chart or metric on its own? Render a single widget instead of the whole dashboard:

```tsx theme={null}
import { WisdomProvider, DashboardWidget } from '@wisdomai/react';
 
<WisdomProvider theme={/* ... */}>
  <DashboardWidget dashboardId="<your-dashboard-id>" widgetId="<widget-id>" />
</WisdomProvider>
```

## Composable widgets (advanced)

When you want full control over the card *around* a widget, including your own container, header, spacing, menus, and empty/loading states, drop down to the composable layer. Instead of Wisdom's pre-built widget card, you render just the visualization and wrap it in your own markup.

```tsx theme={null}
import {
  WisdomProvider,
  DashboardProvider,
  useDashboardWidget,
  WisdomVisualization,
} from '@wisdomai/react';
 
function BrandCard({ widgetId }: { widgetId: string }) {
  const { widget, status, error, fetchMore } = useDashboardWidget(widgetId);
 
  if (status === 'loading') return <YourSkeleton />;
  if (error || !widget) return <YourError message={error} />;
 
  return (
    <section className="your-card">
      <h3>{widget.title}</h3>
      <WisdomVisualization visualization={widget.visualization} fetchMore={fetchMore} />
    </section>
  );
}
 
export default function App() {
  return (
    <WisdomProvider theme={/* ... */}>
      <DashboardProvider dashboardId="<your-dashboard-id>">
        <BrandCard widgetId="<widget-id>" />
      </DashboardProvider>
    </WisdomProvider>
  );
}
```

`DashboardProvider` loads the dashboard once; each `useDashboardWidget(widgetId)` reads a widget from it and returns the live `visualization` plus a `fetchMore` callback for paginating large series. `WisdomVisualization` renders the chart, metric, or table itself, with no Wisdom-supplied title bar or kebab menu, so the surrounding card is entirely yours.

<Note>
  The composable layer (`DashboardProvider`, `useDashboardWidget`, `WisdomVisualization`) is the lower-level building block beneath `Dashboard` and `DashboardWidget`. Reach for it whenever you want full control over the UI around a widget. As the SDK is still pre-1.0 (`0.0.x`), these APIs may see small changes between releases. Let your Wisdom contact know what you're building and we'll give you a heads-up on anything that affects you.
</Note>

## Filters

Wisdom dashboards can be filtered three ways, from zero-effort to fully custom.

**1. Built-in filter bar (default).** `<Dashboard>` already renders a filter bar above its widgets, so your end users can filter without any extra work on your side.

**2. Decoupled filters: place the filter UI anywhere.** To move the filter controls out of the dashboard and into your own layout, such as a sidebar, a toolbar, or a drawer, compose the pieces under a single `DashboardProvider`. The filters and the widgets share that provider's state, so controls placed anywhere drive the same dashboard:

```tsx theme={null}
import {
  WisdomProvider,
  DashboardProvider,
  DashboardFilters,
  DashboardWidgets,
} from '@wisdomai/react';
 
<WisdomProvider theme={/* ... */}>
  <DashboardProvider dashboardId="<your-dashboard-id>">
    <aside className="your-sidebar">
      <DashboardFilters direction="column" />
    </aside>
    <main>
      <DashboardWidgets />
    </main>
  </DashboardProvider>
</WisdomProvider>
```

`DashboardFilters` takes a `direction` of `'row'` (default) or `'column'`. Because `DashboardFilters` and `DashboardWidgets` read the **same** `DashboardProvider`, the filter controls drive the widgets no matter where you place them in your layout. The controls must share a provider with the widgets. A `DashboardFilters` placed next to a self-contained `<Dashboard>` (which creates its own provider internally) will not drive it.

<Note>
  Decoupled filters use the composable layer (`DashboardProvider` + `DashboardWidgets`) described above. The all-in-one `<Dashboard>` already includes the built-in filter bar, so use this approach when you want to place the filter controls somewhere `<Dashboard>` won't put them.
</Note>

**3. Headless: drive filters from your own state.** For full control, `useDashboardFilters()` (called inside a `DashboardProvider`) returns the live filter specs plus a `setFilterValue(filterId, value)` mutator, so you can build your own filter inputs and apply them programmatically.

## Next steps

<CardGroup>
  <Card title="Authentication" icon="Key" href="/integrations/embeddings/sdk/sdk-auth">
    Secure your integration that keeps your access token on the server and out of the browser.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/integrations/embeddings/sdk/sdk-quickstart">
    Set up the SDK and embed your first dashboard in minutes.
  </Card>
</CardGroup>


# SDK Overview
Source: https://docs.wisdom.ai/integrations/embeddings/sdk/sdk-overview



Embed live WisdomAI dashboards directly inside your own React application. The SDK renders Wisdom's interactive analytics: charts, metrics, tables and filters as native React components in your DOM (no iframe). They flow with your layout and inherit your theming, placed inside your own pages like any other component.

## What you can do today

* **Embed a full dashboard**: Drop an entire Wisdom dashboard into a page with a single component.
* **Embed a single widget**: Render one chart, metric, or table on its own and place it anywhere in your UI.
* **Chat**: Embed a conversation surface where viewers ask questions in natural language and get streamed answers, charts, tables, and narratives, with or without a dashboard.
* **DashChat**: Attach that chat to a dashboard as a side panel scoped to the dashboard's own domains, with follow-up questions seeded from any widget.
* **Brand-native widget cards (advanced)**: Render a widget's visualization without Wisdom's built-in card chrome and wrap it in your own container (see Components).
* **Interactive analytics**: Charts, time series, stacked breakdowns, data tables, and KPI metrics, all fully interactive (zoom, tooltips, export-to-data).
* **Filtering**: Show Wisdom's built-in filter bar, or drive filters from your own application state.
* **Theming**: Match the embedded content to your product's colors, typography, and chart palette.
* **Multi-tenant ready**: Issue per-user tokens so each of your end users only sees the data they're entitled to.

## Packages

The SDK is published publicly on the **npm registry** under the `@wisdomai` scope:

| Package           | Registry                                                                      | Use                                                                                                                                         |
| ----------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `@wisdomai/react` | [npmjs.com/package/@wisdomai/react](http://npmjs.com/package/@wisdomai/react) | React component library: providers, `Dashboard`, widgets, hooks. Runs in the browser.                                                       |
| `@wisdomai/node`  | [npmjs.com/package/@wisdomai/node](http://npmjs.com/package/@wisdomai/node)   | Server-side helper that exchanges your long-lived access token for a short-lived JWT the browser can safely use. Runs on your backend only. |

<Note>
  Both packages are MIT-licensed and ESM-first.
</Note>

## How the docs are organized

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/integrations/embeddings/sdk/sdk-quickstart">
    Install, wire up auth, and render your first dashboard.
  </Card>

  <Card title="Components" icon="react" href="/integrations/embeddings/sdk/sdk-components">
    Embed dashboards, single widgets, custom widget cards, and filters.
  </Card>

  <Card title="Authentication" icon="key" href="/integrations/embeddings/sdk/sdk-auth">
    The `@wisdomai/node` token exchange, `WisdomProvider`, and per-user (multi-tenant) tokens.
  </Card>
</CardGroup>

## What's coming

Dashboard consumption, Chat, and DashChat are available today (see [Components](/integrations/embeddings/sdk/sdk-components#chat)). On the near-term roadmap:

* **List views**: Dashboard and conversation lists, so an embed can offer browsing and chat history.
* **Dashboard authoring**: Create and edit dashboards directly from the SDK.
* **Agents**: Scheduled and triggered analysis in the embed.

## FAQs

<AccordionGroup>
  <Accordion title="Is this a React-only SDK?">
    The current release is React. Web component and framework-agnostic support is on the roadmap.
  </Accordion>

  <Accordion title="How does authentication work?">
    `WisdomProvider` accepts a `tokenProvider` function that returns a JWT. Your backend controls token generation and expiry. No WisdomAI credentials are exposed in the browser.
  </Accordion>

  <Accordion title="Does the SDK support multi-tenant isolation with row-level security?">
    Yes. JWT-based authentication carries the user's identity, which WisdomAI uses to enforce row-level security. Each embedded user sees only their own data.
  </Accordion>

  <Accordion title="What happens when the JWT expires?">
    A `tokenProvider` that returns a fresh token on each call is the recommended pattern for long-lived sessions.
  </Accordion>

  <Accordion title="Is the iframe embedding approach still supported?">
    Yes. The iframe path remains available and unchanged. The SDK is an additive option for teams that need composability, theming, or programmatic filter control beyond what iframes support.
  </Accordion>

  <Accordion title="Can we customize which dashboard filters are shown?">
    `WisdomGlobalFilters` renders the filters configured on the dashboard. Refs and callbacks give your application programmatic control over the filter state for tighter native integration.
  </Accordion>

  <Accordion title="Chat and DasChat Version">
    Chat and DashChat ship in `@wisdomai/react@0.0.12`, currently published on the `next` npm tag: `npm install @wisdomai/react@next`.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/integrations/embeddings/sdk/sdk-quickstart">
    Set up the SDK and embed your first dashboard in minutes.
  </Card>

  <Card title="Components" icon="react" href="/integrations/embeddings/sdk/sdk-components">
    Browse the React components available for embed a full dashboard, composable widgets, and filters.
  </Card>
</CardGroup>


# SDK Quickstart
Source: https://docs.wisdom.ai/integrations/embeddings/sdk/sdk-quickstart



Get a live, interactive WisdomAI dashboard rendering in your React app. You'll install the packages, add a small backend endpoint that mints a short-lived token, and drop in a `<Dashboard>` component.

## Requirements

Before you begin, ensure you have:

* **React 18+** and **react-dom 18+**
* **MUI v7** (`@mui/material`, `@mui/x-date-pickers`) — note the major version
* **Emotion 11** (`@emotion/react`, `@emotion/styled`)
* **Highcharts 12** + `highcharts-react-official` 3
* **GraphQL 16**, **Luxon 3**
* ESM-only: use a modern bundler (Vite, Next.js, etc.)
* A reachable Wisdom `baseUrl` over **HTTPS**

## Integration

Follow these steps to get the SDK running in your app:

### 1. Install

Run the following commands:

```bash theme={null}
npm install @wisdomai/react
npm install @wisdomai/node   # backend only
```

The React SDK relies on a few peer dependencies your app must also have installed (see [Requirements](#requirements)):

```bash theme={null}
npm install react react-dom \
  @mui/material@^7 @mui/x-date-pickers@^7 \
  @emotion/react@^11 @emotion/styled@^11 \
  highcharts@^12 highcharts-react-official@^3 \
  graphql@^16 luxon@^3
```

### 2. Add the token-exchange endpoint

Your long-lived access token is a secret and must never reach the browser. Add a small backend endpoint that exchanges it for a short-lived JWT:

```jsx theme={null}
import express from 'express';
import { WisdomAI } from '@wisdomai/node';
 
const wisdom = new WisdomAI({
  accessToken: process.env.WISDOM_ACCESS_TOKEN, // keep this server-side
  baseUrl: process.env.WISDOM_BASE_URL,         // e.g. https://your-org.gowisdom.ai
});
 
const app = express();
app.post('/auth-token', async (_req, res) => {
  res.json(await wisdom.getAuthToken());
});
app.listen(3000);
```

Serve `/auth-token` from the **same origin** as your frontend (or proxy it), so the browser request needs no extra CORS or credentials handling.

<Note>
  This is the minimum to get a token. For how the exchange works, per-user (multi-tenant) tokens, and token refresh, see [Authentication](/integrations/embeddings/sdk/sdk-auth).
</Note>

### 3. Render a dashboard

Drop `<Dashboard>` inside `WisdomProvider` and pass your dashboard ID:

```tsx theme={null}
import { WisdomProvider, Dashboard } from '@wisdomai/react';
 
export default function App() {
  return (
    <WisdomProvider
      theme={{
        primaryTextColor: '#111827',
        secondaryTextColor: '#6b7280',
        background: '#ffffff',
        border: '#e5e7eb',
      }}
    >
      <Dashboard dashboardId="<your-dashboard-id>" />
    </WisdomProvider>
  );
}
```

By default `WisdomProvider` fetches the JWT from `/auth-token`. That's all you need to render a live, interactive dashboard.

<Note>
  For more ways to embed (single widgets, custom cards, filters), see [Components](/integrations/embeddings/sdk/sdk-components).
</Note>

## Theming

Pass a `theme` object to `WisdomProvider` to match the embedded content to your product. Four keys are required; the rest are optional.

| Key                  | Required | Description                            |
| -------------------- | -------- | -------------------------------------- |
| `primaryTextColor`   | Yes      | Main text color (titles, values).      |
| `secondaryTextColor` | Yes      | Muted text (axis labels, captions).    |
| `background`         | Yes      | Surface/background color.              |
| `border`             | Yes      | Border and divider color.              |
| `fontFamily`         | No       | Font stack for embedded content.       |
| `chartColors`        | No       | Array of colors used for chart series. |

<Note>
  Always pass an explicit `theme`. Supplying the four required keys ensures the embedded components render with your brand rather than defaults.
</Note>

## Next steps

<CardGroup>
  <Card title="Authentication" icon="Key" href="/integrations/embeddings/sdk/sdk-auth">
    Secure your integration that keeps your access token on the server and out of the browser.
  </Card>

  <Card title="Components" icon="react" href="/integrations/embeddings/sdk/sdk-components">
    Browse the React components available for embed a full dashboard, composable widgets, and filters.
  </Card>
</CardGroup>


# Session Management
Source: https://docs.wisdom.ai/integrations/embeddings/session-management



Embedded session JWTs expire after one hour. WisdomAI provides a built-in `postMessage` mechanism that lets your application refresh the token before expiry without interrupting the user's session.

## Token lifetime

| Property | Value                                                           |
| -------- | --------------------------------------------------------------- |
| Lifetime | 1 hour                                                          |
| Storage  | `localStorage` as `wisdom.jwt`                                  |
| Override | `?token=` URL param always takes priority over any cached token |

## Built-in refresh via postMessage

WisdomAI sends a `REQUEST_JWT_TOKEN` event to the parent window approximately 10 seconds before the embedded token expires. It is your responsibility to listen for this event, generate a fresh token by calling `impersonateUser` from your backend, and post it back. WisdomAI picks up the new token and continues the session without interruption.

### Flow

1. WisdomAI iframe detects the token is about to expire.
2. WisdomAI sends `window.parent.postMessage({ type: 'REQUEST_JWT_TOKEN' }, '*')` to the host.
3. Your host receives the event and validates `event.origin` matches the WisdomAI domain.
4. Your host calls `impersonateUser` via your own backend to get a fresh JWT.
5. Your host posts back `iframe.contentWindow.postMessage({ type: 'JWT_TOKEN_RESPONSE', token }, WISDOM_ORIGIN)`.
6. WisdomAI receives the new token and refreshes the session.

### Implementation example

<Note>
  Replace `{ACCOUNT}.wisdom.ai` with the base URL of your WisdomAI tenant — the same domain you use to log in. Both `wisdom.ai` and `askwisdom.ai` are valid depending on your deployment.
</Note>

```html theme={null}
<iframe
  id="wisdom-frame"
  src="https://{ACCOUNT}.wisdom.ai/embed/dashboards/<id>?token=<JWT>"
  allow="microphone; camera; clipboard-write"
  style="width:100%;height:800px;border:0"
></iframe>

<script>
  const iframe = document.getElementById('wisdom-frame');
  // Replace with your actual WisdomAI tenant domain
  const WISDOM_ORIGIN = 'https://{ACCOUNT}.wisdom.ai';

  async function getFreshWisdomToken() {
    // Call your own backend, which calls impersonateUser with the access key.
    const response = await fetch('/api/wisdom-token');
    const data = await response.json();
    return data.token;
  }

  window.addEventListener('message', async (event) => {
    if (event.origin !== WISDOM_ORIGIN) return;
    if (event.source !== iframe.contentWindow) return;
    if (event.data?.type !== 'REQUEST_JWT_TOKEN') return;

    try {
      const token = await getFreshWisdomToken();
      iframe.contentWindow.postMessage(
        { type: 'JWT_TOKEN_RESPONSE', token },
        WISDOM_ORIGIN
      );
    } catch (error) {
      console.error('Unable to provide Wisdom token', error);
    }
  });
</script>
```

### Implementation notes

* WisdomAI sends the request with `'*'` as the target origin. You must validate `event.origin` on your side before handling the message.
* If your host does not respond within 10 seconds, the request times out and retries on the next render cycle.
* Only one refresh request is in-flight at a time. Duplicate requests are suppressed automatically.
* The `?token=` URL param always takes priority over any cached token in `localStorage`.

## Switching users

The WisdomAI frontend stores the active session token in `localStorage` as `wisdom.jwt`. To switch the impersonated user in the same iframe, reload the iframe with a new JWT in the `?token=` URL param rather than attempting to swap the token in place.

```js theme={null}
// Switch to a different user by reloading the iframe src
iframe.src = `https://{ACCOUNT}.wisdom.ai/embed/search?token=${newJWT}`;
```

There is no explicit logout mutation for embedded sessions.

## Expired or invalid tokens

When an expired or invalid JWT is passed in the embed URL, users may be redirected to the login page instead of seeing a clear error. To prevent this, implement the `postMessage` refresh listener described above so that tokens are refreshed before expiry.

## Related articles

<CardGroup>
  <Card title="Impersonate User" icon="user-secret" href="/integrations/graphql-api/mutations/auth/impersonate-user">
    Generate a session JWT for an embedded user
  </Card>

  <Card title="Embedding Overview" icon="code" href="/integrations/embeddings/embedding">
    Full server-side embedding flow
  </Card>

  <Card title="User Lifecycle" icon="users" href="/integrations/user-management/user-lifecycle">
    Create, update, and remove embedded users
  </Card>
</CardGroup>


# Google Sheets
Source: https://docs.wisdom.ai/integrations/google-sheets



The WisdomAI integration for Google Sheets allows you to pull live data from your WisdomAI dashboards directly into Google Sheets. You can import any widget from your dashboards and chats using custom formulas or a visual dialog, and extract the latest version of data, everything with a single click.

## Get started

Before you begin, ensure you have the **API Credentials**:

Email [support@askwisdom.ai](mailto:support@askwisdom.ai) to request API keys for the Google Sheets integration, along with the use case. The WisdomAI team will reply with **your API token** and **the wrapper script**.

## Set up the integration

Follow these steps to integrate your Google Sheets with WisdomAI:

1. Open your Google Sheet and go to **Extensions** > **Apps Script**.
2. In the script editor, click the **+** icon next to Libraries.

<Frame>
  <img alt="Snippet showing the Add Extension Selector" />
</Frame>

3. Enter the Script ID: `1fx_yQncdXWvARZH0TuBpy7-XECy5VWi2gJ3JPPa2kCfCVp9elsyHPZK8` and click **Look up**.
4. Select the latest version.
5. Set the identifier as **WisdomGoogleSheets**.
6. Click **Add**.
   <Frame>
     <img alt="Add Library" />
   </Frame>
7. Paste the wrapper script shared by [support@askwisdom.ai](mailto:support@askwisdom.ai) into Code.gs, replacing any existing code.
8. Save and reload your spreadsheet. Once synced, a WisdomAI menu will appear in the menu bar.

## Set up your account

To configure your account, follow these steps:

1. In your Google Sheet, go to **Wisdom AI** > **Configure Account** from the menu bar.
2. Enter your Account URL and the API Token you received.
3. Click **Save Configuration**.

<Frame>
  <img alt="Snippet showing the account configuration option and the credentials modal" />
</Frame>

4. Go to **Wisdom AI** > **Test Connection** to verify that everything works.

<Frame>
  <img alt="" />
</Frame>

## Visual widget

To insert a visual widget, follow these steps:

1. Go to **Wisdom AI** > **Insert Widget**.

<Frame>
  <img alt="insert-widget" />
</Frame>

2. Paste the widget URL from your Wisdom dashboard
3. On any widget, click the menu and select **Copy link to visualization**. You can choose which rows and columns to import and whether to include headers.

## Custom formulas

You can also use these formulas directly in cells:

| Formula                                      | What it does               |
| :------------------------------------------- | :------------------------- |
| `=WISDOM_WIDGET`(dashboardId, widgetId)      | Fetches data from a widget |
| `=WISDOM_COLUMN`(dashboardId, widgetId, col) | Fetches a single column    |

## Refreshing data

To update everything, go to **Wisdom AI** > **Refresh All Data**. This re-fetches every WisdomAI formula in the active sheet.

<Frame>
  <img alt="refresh-data" />
</Frame>

## Next Steps

<CardGroup>
  <Card icon="message" href="/integrations/embeddings/iframe/embed-chat" title="Embed Chat">
    Discover how to embed conversational AI chat interfaces
  </Card>

  <Card title="Connect to Slack" icon="slack" href="/integrations/connect-to-slack">
    Learn how to connect WisdomAI to Slack.
  </Card>
</CardGroup>


# GraphQL API
Source: https://docs.wisdom.ai/integrations/graphql-api/GraphQL-API



Create seamless integrations with WisdomAI using our comprehensive GraphQL API. Access domains, tables, and analytics data programmatically to build custom applications and workflows.

<Note>
  The GraphQL API is designed for external integrations. All operations require proper authentication and respect your organization's access controls.
</Note>

## Get started

The WisdomAI GraphQL API provides a single endpoint for all operations:

```text theme={null}
https://{ACCOUNT}.askwisdom.ai/graphql
```

<Note>
  Replace `{ACCOUNT}.askwisdom.ai` with the base URL of your WisdomAI tenant, the same domain you use to log in. Both `askwisdom.ai` and `wisdom.ai` are valid depending on your deployment.
</Note>

The API supports queries, mutations, and real-time subscriptions. Subscriptions use a WebSocket-based model that lets users ask questions related to business intelligence and receive structured responses, including tabular data and SQL queries.

## WebSocket connection

For real-time subscriptions, use the following WebSocket endpoint:

```text theme={null}
wss://{ACCOUNT}.askwisdom.ai/graphql
```

## Authentication

WisdomAI supports two authentication flows depending on your use case:

### API authentication

For direct API access, authenticate using a JWT session token obtained via the Descope authentication system.

<Steps>
  <Step title="Obtain access key">
    Every WisdomAI user can create and manage their own API keys. To obtain your dedicated access key, follow the steps in [this article](/settings/api-keys).
  </Step>

  <Step title="Exchange access key for JWT token">
    Use WisdomAI's GraphQL API `exchangeAccessToken` query to exchange your access key for a JWT token.

    ```graphql theme={null}
    query ExchangeAccessToken($accessToken: String!) {
      exchangeAccessToken(accessToken: $accessToken)
    }
    ```
  </Step>

  <Step title="Pass token in requests">
    Include the session token in all API requests and WebSocket connection payloads.

    ```text theme={null}
    Authorization: Bearer YOUR_SESSION_TOKEN
    ```
  </Step>
</Steps>

### Embedded user authentication

For embedding scenarios, the flow is different. Instead of `exchangeAccessToken`, you call `impersonateUser` with your Descope access key to obtain a short-lived JWT for the embedded user. That JWT is passed as the `token` query parameter in the iframe URL, not in an `Authorization` header.

See the [Embedding overview](/integrations/embeddings/embedding) for the full end-to-end flow.

## Error handling

<Warning>
  The WisdomAI GraphQL API returns **HTTP 200 even when an operation fails**. Always inspect the response body, not the HTTP status code. See [Error handling](/integrations/embeddings/error-handling) for the full reference including response shapes and status codes.
</Warning>

<Info>
  For any queries or support, contact our API team at [**support@askwisdom.ai**](mailto:support@askwisdom.ai).
</Info>

## Related articles

<CardGroup>
  <Card title="GraphQL primer" icon="book" href="/integrations/graphql-api/graphql-primer">
    New to GraphQL? Start here for a REST developer's introduction
  </Card>

  <Card title="Exchange Access Token" icon="key" href="/integrations/graphql-api/queries/auth/exchange-access-token">
    Authenticate with the GraphQL API using access keys
  </Card>

  <Card title="Queries" icon="magnifying-glass" href="/integrations/graphql-api/queries/user/current-user">
    Learn about available queries for fetching data
  </Card>

  <Card title="Mutations" icon="pen-to-square" href="/integrations/graphql-api/mutations/chat/create-conversation">
    Discover mutations for creating and updating resources
  </Card>

  <Card title="Subscriptions" icon="wifi" href="/integrations/graphql-api/subscriptions/subscribe-conversation">
    Real-time data subscriptions and live updates
  </Card>

  <Card title="Error handling" icon="circle-exclamation" href="/integrations/embeddings/error-handling">
    How to handle HTTP 200 failures and mutation status codes
  </Card>
</CardGroup>


# GraphQL Primer for REST Developers
Source: https://docs.wisdom.ai/integrations/graphql-api/graphql-primer



If you're used to REST APIs, GraphQL has a few key differences worth knowing before you start. This page covers the essentials so you can make your first request quickly.

## One endpoint, one method

Unlike REST, which uses many endpoints (`GET /users`, `POST /dashboards`, etc.), GraphQL uses a **single endpoint** for all operations:

```text theme={null}
https://{ACCOUNT}.askwisdom.ai/graphql
```

Every request is a **POST** with a JSON body containing two fields:

| Field       | Description                                             |
| ----------- | ------------------------------------------------------- |
| `query`     | The GraphQL operation (query or mutation) as a string   |
| `variables` | A JSON object with input values referenced in the query |

```bash theme={null}
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "query": "query ListUsers($workspaceId: ID) { listUsers(workspaceId: $workspaceId) { id email } }",
    "variables": {
      "workspaceId": "workspace_123"
    }
  }' \
  https://{ACCOUNT}.askwisdom.ai/graphql
```

## HTTP 200 does not mean success

This is the most important difference from REST. **GraphQL can return HTTP 200**, even **when the operation fails**. Do not check the HTTP status code to determine success, always inspect the response body.

Errors appear in an `errors` array:

```json theme={null}
{
  "errors": [
    {
      "message": "Unauthorized",
      "locations": [{ "line": 1, "column": 1 }]
    }
  ],
  "data": null
}
```

For mutations, also check the `status.code` field in the response data:

```json theme={null}
{
  "data": {
    "createUsers": {
      "status": {
        "code": "ERROR",
        "message": "User already exists"
      }
    }
  }
}
```

See [Error handling](/integrations/embeddings/error-handling) for details.

## Postman setup

To call the WisdomAI GraphQL API from Postman:

1. Set method to **POST**
2. URL: `https://{ACCOUNT}.askwisdom.ai/graphql`
3. Headers:
   * `Content-Type: application/json`
   * `Authorization: Bearer <your_token>`
4. Body → **raw** → **JSON**:
   ```json theme={null}
   {
     "query": "query ListUsers($workspaceId: ID) { listUsers(workspaceId: $workspaceId) { id email } }",
     "variables": {
       "workspaceId": "workspace_123"
     }
   }
   ```

## Common mistakes

| Mistake                                   | Fix                                                                                            |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Missing `Content-Type: application/json`  | Always include this header — without it, the server can't parse the body                       |
| Sending the query as a URL parameter      | GraphQL queries go in the POST body, not the URL                                               |
| Not requesting return fields on mutations | Include `status { code message }` (or other fields) in your mutation or they won't be returned |
| Checking HTTP status for errors           | Always read the response body. GraphQL returns HTTP 200 even on failure                        |

## Related articles

<CardGroup>
  <Card title="GraphQL API overview" icon="code" href="/integrations/graphql-api/GraphQL-API">
    Endpoint, authentication, and error handling
  </Card>

  <Card title="User management" icon="users" href="/integrations/user-management/user-lifecycle">
    Create, update, and manage users via API
  </Card>

  <Card title="Queries" icon="magnifying-glass" href="/integrations/graphql-api/queries/user/current-user">
    Available read operations
  </Card>

  <Card title="Mutations" icon="pen-to-square" href="/integrations/graphql-api/mutations/chat/create-conversation">
    Available write operations
  </Card>
</CardGroup>


# Trigger Agent
Source: https://docs.wisdom.ai/integrations/graphql-api/mutations/agent/trigger-agent



The `triggerSchedule` mutation allows you to manually trigger an existing agent to run immediately.

Refer to the [Agents documentation](/setting-up-wisdom-ai/agents/agents) to learn more about how to configure and use them.

## Signature

```graphql theme={null}
triggerSchedule(id: String!): Boolean!
```

<Note>
  This mutation can only be executed if you have view access for the agent.
</Note>

## Arguments

<ParamField type="String!">
  The unique identifier of the agent to trigger. You can find it in the URL of the agent edit page.
</ParamField>

## Response

Returns a `Boolean` indicating whether the trigger was successful.

## Usage example

Trigger an existing agent schedule:

```graphql theme={null}
mutation TriggerAgent($scheduleId: String!) {
  success: triggerSchedule(id: $scheduleId)
}
```

<RequestExample>
  ```bash Request theme={null}
  curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer your_api_key" \
    -d '{
      "query": "mutation TriggerAgent($scheduleId: String!) { success: triggerSchedule(id: $scheduleId) }",
      "variables": {
        "scheduleId": "schedule_987654321"
      }
    }' \
    https://{ACCOUNT}.askwisdom.ai/graphql
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "data": {
      "triggerSchedule": true
    }
  }
  ```
</ResponseExample>

## Related operation

<CardGroup>
  <Card title="Send User Message" icon="message" href="/integrations/graphql-api/mutations/chat/send-user-message">
    Send a message to the conversation
  </Card>
</CardGroup>


# Impersonate User
Source: https://docs.wisdom.ai/integrations/graphql-api/mutations/auth/impersonate-user



The `impersonateUser` mutation exchanges a permanent access key for a short-lived JWT token that authenticates subsequent requests as a specific user. This is the core of the embedded session flow — the returned JWT is passed as the `token` query parameter in iframe embed URLs.

This mutation is public and unauthenticated — no `Authorization` header is required.

## Signature

```graphql theme={null}
impersonateUser(accessToken: String!, userEmail: String!, attributes: [UserAttributeInput!]): String!
```

## Parameters

<ParamField type="String!">
  Your permanent Descope access key. This is not a JWT or a prior session token — it is the long-lived key obtained from `support@askwisdom.ai`. Must be kept secret and only used server-side.
</ParamField>

<ParamField type="String!">
  The email address of the user to impersonate. The user must already exist in Wisdom — call [`createUsers`](/integrations/graphql-api/mutations/user/create-users) first if needed.
</ParamField>

<ParamField type="[UserAttributeInput!]">
  Optional key-value pairs applied **only for this session**. These override DATABASE-sourced attributes for the duration of the session and are not persisted. Useful for passing context that should not be stored on the user (e.g., a specific report context or request-scoped filter).

  <Warning>
    The `impersonated_user_id` claim cannot be overridden via attributes.
  </Warning>

  See [User Attributes](/integrations/user-management/user-attributes) for how attribute sources are prioritized.
</ParamField>

## Response

Returns a raw `String!` — the short-lived JWT to use as the `token` query parameter in iframe embed URLs. The token expires after **1 hour**.

<Warning>
  Never expose your permanent access key in client-side code. Always call this mutation from your server. See [Embed a Chat and Dashboards](/integrations/embeddings/embedding) for the secure server-side flow.
</Warning>

## Usage example

```graphql theme={null}
mutation ImpersonateUser($accessToken: String!, $userEmail: String!) {
  impersonateUser(accessToken: $accessToken, userEmail: $userEmail)
}
```

<RequestExample>
  ```bash Without attributes theme={null}
  curl -X POST \
    -H "Content-Type: application/json" \
    -d '{
      "query": "mutation ImpersonateUser($accessToken: String!, $userEmail: String!) { impersonateUser(accessToken: $accessToken, userEmail: $userEmail) }",
      "variables": {
        "accessToken": "<your_access_key>",
        "userEmail": "alice@yourcompany.com"
      }
    }' \
    https://{ACCOUNT}.askwisdom.ai/graphql
  ```

  ```bash With transient attributes theme={null}
  curl -X POST \
    -H "Content-Type: application/json" \
    -d '{
      "query": "mutation ImpersonateUser($accessToken: String!, $userEmail: String!, $attributes: [UserAttributeInput!]) { impersonateUser(accessToken: $accessToken, userEmail: $userEmail, attributes: $attributes) }",
      "variables": {
        "accessToken": "<your_access_key>",
        "userEmail": "alice@yourcompany.com",
        "attributes": [
          { "key": "report_id", "value": "q3-sales-summary" },
          { "key": "customer_id", "value": "cust_789" }
        ]
      }
    }' \
    https://{ACCOUNT}.askwisdom.ai/graphql
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "data": {
      "impersonateUser": "eyJhbGciOiJSUzI1NiIsInR5..."
    }
  }
  ```
</ResponseExample>

<Tip>
  Attributes that are stable for a given user (such as `account_id`) should be set permanently via [`createUsers`](/integrations/graphql-api/mutations/user/create-users) or [`setUserAttributes`](/integrations/graphql-api/mutations/user/set-user-attributes). Attributes that change per session (such as a selected view or context) can be passed transiently via `attributes` here.
</Tip>

## Token lifecycle and refresh

| Property | Value                                                             |
| -------- | ----------------------------------------------------------------- |
| Lifetime | 1 hour                                                            |
| Refresh  | Via `postMessage` (see below)                                     |
| Priority | `?token=` URL param always takes precedence over any cached token |

### Built-in refresh via `postMessage`

WisdomAI sends a `REQUEST_JWT_TOKEN` event to the parent window approximately 10 seconds before the embedded token expires. It is the **embedder's responsibility** to listen for this event, regenerate the token by calling `impersonateUser` from their backend, and post it back. WisdomAI then picks up the new token and continues the session seamlessly.

**Flow:**

1. WisdomAI iframe detects the token is about to expire
2. WisdomAI sends `window.parent.postMessage({ type: 'REQUEST_JWT_TOKEN' }, '*')` to the host
3. Host receives the event and validates `event.origin` matches the WisdomAI domain
4. Host calls `impersonateUser` via its own backend to get a fresh JWT
5. Host posts back `iframe.contentWindow.postMessage({ type: 'JWT_TOKEN_RESPONSE', token }, WISDOM_ORIGIN)`
6. WisdomAI receives the new token and refreshes the session

```html theme={null}
<iframe
  id="wisdom-frame"
  src="https://{ACCOUNT}.askwisdom.ai/embed/dashboards/<id>?token=<JWT>"
  style="width:100%;height:800px;border:0"
></iframe>

<script>
  const iframe = document.getElementById('wisdom-frame');
  const WISDOM_ORIGIN = 'https://{ACCOUNT}.askwisdom.ai';

  async function getFreshWisdomToken() {
    // Call your own backend, which calls impersonateUser with the access key
    const response = await fetch('/api/wisdom-token');
    const data = await response.json();
    return data.token;
  }

  window.addEventListener('message', async (event) => {
    if (event.origin !== WISDOM_ORIGIN) return;
    if (event.source !== iframe.contentWindow) return;
    if (event.data?.type !== 'REQUEST_JWT_TOKEN') return;

    try {
      const token = await getFreshWisdomToken();
      iframe.contentWindow.postMessage(
        { type: 'JWT_TOKEN_RESPONSE', token },
        WISDOM_ORIGIN
      );
    } catch (error) {
      console.error('Unable to provide WisdomAI token', error);
    }
  });
</script>
```

**Implementation notes:**

* WisdomAI sends with `'*'` as target origin — the host **must** validate `event.origin` on its side
* If the host does not respond within **10 seconds**, the request times out and retries on the next render cycle
* Only one refresh request is in-flight at a time (duplicate requests are suppressed)
* The `?token=` URL param always takes priority over any cached token

## Related articles

<CardGroup>
  <Card title="Embed a Dashboard" icon="chart-bar" href="/integrations/embeddings/iframe/embed-a-dashboard">
    Use the token in an iframe embed URL
  </Card>

  <Card title="Embed a Chat" icon="message" href="/integrations/embeddings/iframe/embed-chat">
    Use the token for embedded chat
  </Card>

  <Card title="Create Users" icon="user-plus" href="/integrations/graphql-api/mutations/user/create-users">
    Create users before impersonating them
  </Card>

  <Card title="User Attributes" icon="list" href="/integrations/user-management/user-attributes">
    Understand transient vs persistent attributes
  </Card>

  <Card title="Session Management" icon="clock" href="/integrations/embeddings/session-management">
    Full token lifecycle reference, including switching users
  </Card>
</CardGroup>


# Create Conversation
Source: https://docs.wisdom.ai/integrations/graphql-api/mutations/chat/create-conversation



The `createConversation` mutation creates a new conversation in a specified domain for conducting AI-powered data analysis sessions.

## Signature

```graphql theme={null}
createConversation(domainId: String!, hidden: Boolean!): ID!
```

## Arguments

<ParamField type="String!">
  The unique identifier of the domain where the conversation will be created.
</ParamField>

<ParamField type="Boolean!">
  Whether the conversation should be hidden from the user interface.
</ParamField>

## Response

Returns an `ID` representing the unique identifier of the newly created conversation.

## Usage example

Create a new conversation for data analysis:

```graphql theme={null}
mutation CreateConversation(
  $domainId: String!
  $hidden: Boolean!
) {
  id: createConversation(
    domainId: $domainId
    hidden: $hidden
  )
}
```

<RequestExample>
  ```bash Request theme={null}
  curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <jwt_token>" \
    -d '{
      "query": "mutation CreateConversation($domainId: String!, $hidden: Boolean!) { id: createConversation(domainId: $domainId, hidden: $hidden) }",
      "variables": {
        "domainId": "domain_123456789",
        "hidden": false
      }
    }' \
    https://{ACCOUNT}.askwisdom.ai/graphql
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "data": {
      "id": "conv_987654321"
    }
  }
  ```
</ResponseExample>

## Related operation

<CardGroup>
  <Card title="Send User Message" icon="message" href="/integrations/graphql-api/mutations/chat/send-user-message">
    Send a message to the conversation
  </Card>
</CardGroup>


# Send User Message
Source: https://docs.wisdom.ai/integrations/graphql-api/mutations/chat/send-user-message



The `sendUserMessage` mutation sends a user's message or question to an existing conversation, triggering AI-powered analysis and response generation.

## Signature

```graphql theme={null}
sendUserMessage(
  conversationId: String!
  domainId: String!
  query: DeltaInput!
  createHiddenConversation: Boolean
  toolSelection: ToolSelection
  selectedModelName: String
  isUserOnboarding: Boolean
  editArtifactMode: Boolean
  chatThinkingEffort: ChatThinkingEffort
  disableClarifications: Boolean
  enableDeepAnalysis: Boolean
  isEvaluatingTrigger: Boolean
): ResponseStatus!
```

## Arguments

<ParamField type="String!">
  The unique identifier of the conversation to send the message to.
</ParamField>

<ParamField type="String!">
  The unique identifier of the domain containing the conversation.
</ParamField>

<ParamField type="DeltaInput!">
  The user's message content. See [DeltaInput](/integrations/graphql-api/objects/delta-input).
</ParamField>

<ParamField type="Boolean">
  Whether to create a hidden conversation if needed. Defaults to false.
</ParamField>

<ParamField type="ToolSelection">
  Specific tools to use for processing the message.

  * Use `TABULAR_DATA` to enable querying databases.
  * Use `TEXTUAL_DATA` to enable querying unstructured documents.

  ```
  "toolSelection": {
    "optInToolNames": [
        "TABULAR_DATA",
        "TEXTUAL_DATA"
      ]
    }
  ```

  See [ToolSelection](/integrations/graphql-api/objects/tool-selection).
</ParamField>

<ParamField type="String">
  The name of the AI model to use for response generation.
</ParamField>

<ParamField type="Boolean">
  Whether this message is part of user onboarding. Defaults to false.
</ParamField>

<ParamField type="Boolean">
  Whether to enable artifact editing mode. Defaults to false.
</ParamField>

<ParamField type="ChatThinkingEffort">
  The level of thinking effort to apply. See [ChatThinkingEffort](/integrations/graphql-api/objects/chat-thinking-effort).
</ParamField>

<ParamField type="Boolean">
  Whether to disable clarification questions. Defaults to false.
</ParamField>

<ParamField type="Boolean">
  Whether to enable deep analysis mode. Defaults to false.
</ParamField>

<ParamField type="Boolean">
  Whether this is an evaluation trigger. Defaults to false.
</ParamField>

## Response

Returns a `ResponseStatus` object indicating the success or failure of the operation. See [ResponseStatus](/integrations/graphql-api/objects/response-status) for the schema.

## Usage example

Send a question about sales data to a conversation:

```graphql theme={null}
mutation SendUserMessage(
  $conversationId: String!
  $domainId: String!
  $query: DeltaInput!
) {
  sendUserMessage(
    conversationId: $conversationId
    domainId: $domainId
    query: $query
  ) {
    code
    message
  }
}
```

<RequestExample>
  ```bash Request theme={null}
  curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <jwt_token>" \
    -d '{
      "query": "mutation SendUserMessage($conversationId: String!, $domainId: String!, $query: DeltaInput!) { sendUserMessage(conversationId: $conversationId, domainId: $domainId, query: $query) { code message } }",
      "variables": {
        "conversationId": "conv_123456789",
        "domainId": "domain_987654321",
        "query": {
          "ops": [
            {
              "insert": {
                "text": "What were our total sales last quarter?"
              }
            }
          ]
        }
      }
    }' \
    https://{ACCOUNT}.askwisdom.ai/graphql
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "data": {
      "sendUserMessage": {
        "code": "OK",
        "message": "User message sent"
      }
    }
  }
  ```
</ResponseExample>

## Related operation

<CardGroup>
  <Card title="Subscribe Conversation" icon="wifi" href="/integrations/graphql-api/subscriptions/subscribe-conversation">
    Listen for real-time response updates
  </Card>
</CardGroup>


# Refresh Connection
Source: https://docs.wisdom.ai/integrations/graphql-api/mutations/connection/refresh-connection



The `connectionRefresh` mutation triggers an asynchronous job that refreshes the metadata for a data warehouse connection. Specifically, it refreshes the list of databases, tables, and columns for the given connection.

This operation starts a background job and returns immediately without waiting for completion. The refresh process will discover new tables, updated schemas, and column changes in your data warehouse.

## Signature

```graphql theme={null}
connectionRefresh(id: ID!): Boolean!
```

<Note>
  This mutation can only be executed by an administrator or a data administrator of the specific connection ID.
</Note>

<Warning>
  The refresh cannot be triggered when a connection is already in `QUEUED` or `RUNNING` status. Wait for the current sync to complete before starting a new one.
</Warning>

## Arguments

<ParamField type="ID!">
  The unique identifier of the connection to refresh
</ParamField>

## Response

The response returns a `Boolean` indicating whether the refresh job was successfully triggered:

* `true` - Refresh job was successfully started

<Info>
  On failure, the mutation throws a GraphQL error rather than returning `false`.
</Info>

## Usage example

To refresh a connection's metadata, provide the connection ID to the mutation. Here's an example of how this mutation could be used:

```graphql theme={null}
mutation RefreshConnection($id: ID!) {
  connectionRefresh(id: $id)
}
```

<RequestExample>
  ```bash Request theme={null}
  curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <jwt_token>" \
    -d '{
      "query": "mutation RefreshConnection($id: ID!) { connectionRefresh(id: $id) }",
      "variables": {
        "id": "et-connection-id-here"
      }
    }' \
    https://{ACCOUNT}.askwisdom.ai/graphql
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "data": {
      "connectionRefresh": true
    }
  }
  ```
</ResponseExample>

## Next steps

<CardGroup>
  <Card title="Check Refresh Status" icon="clock" href="/integrations/graphql-api/queries/connection/connection">
    Monitor refresh progress with connection query
  </Card>

  <Card title="Create Domain" icon="plus" href="/integrations/graphql-api/mutations/domain/create-domain">
    Create domains after refresh completion
  </Card>
</CardGroup>


# Add Scope Role Assignments for Sharing
Source: https://docs.wisdom.ai/integrations/graphql-api/mutations/dashboard/add-scope-role-assignments-for-sharing



The `addScopeRoleAssignmentsForSharing` mutation grants access to a specific resource (like a Dashboard) by assigning roles to users. This allows you to share Dashboards with individual team members or groups.

## Signature

```graphql theme={null}
addScopeRoleAssignmentsForSharing(
  scopeId: ID!
  scopeRoleAssignments: [ScopeRoleAssignmentInput!]!
  scopeType: ScopeType!
  message: String
): ResponseStatus!
```

## Arguments

<ParamField type="ID!">
  The unique identifier of the resource you want to share (e.g., a Dashboard ID).
</ParamField>

<ParamField type="[ScopeRoleAssignmentInput!]!">
  Array of user-role assignments defining who gets access and what level of access they receive. See [ScopeRoleAssignmentInput](/integrations/graphql-api/objects/scope-role-assignment-input) for the input structure.
</ParamField>

<ParamField type="ScopeType!">
  The type of resource being shared. For Dashboards, this should be `DASHBOARD`.
</ParamField>

<ParamField type="String">
  Optional personal message to include in the sharing notification email sent to recipients.
</ParamField>

## Response

Returns a `ResponseStatus` object indicating the success or failure of the operation:

```json theme={null}
{
  "code": "OK",
  "message": "Role added successfully"
}
```

## Usage example

The following example shows how to share a Dashboard with a colleague:

```graphql theme={null}
mutation AddScopeRoleAssignments($scopeId: ID!, $scopeRoleAssignments: [ScopeRoleAssignmentInput!]!, $scopeType: ScopeType!, $message: String) {
  addScopeRoleAssignmentsForSharing(
    scopeId: $scopeId
    scopeRoleAssignments: $scopeRoleAssignments
    scopeType: $scopeType
    message: $message
  ) {
    code
    message
  }
}
```

<RequestExample>
  ```bash Request theme={null}
  curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <jwt_token>" \
    -d '{
      "query": "mutation AddScopeRoleAssignments($scopeId: ID!, $scopeRoleAssignments: [ScopeRoleAssignmentInput!]!, $scopeType: ScopeType!, $message: String) { addScopeRoleAssignmentsForSharing(scopeId: $scopeId, scopeRoleAssignments: $scopeRoleAssignments, scopeType: $scopeType, message: $message) { code message } }",
      "variables": {
        "scopeId": "story_123456789",
        "scopeRoleAssignments": [
          {
            "roleId": "00000000-0000-0000-0000-000000000009",
            "principalId": "user_987654321"
          }
        ],
        "scopeType": "DASHBOARD",
        "message": "Please review and edit this sales dashboard"
      }
    }' \
    https://{ACCOUNT}.askwisdom.ai/graphql
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "data": {
      "addScopeRoleAssignmentsForSharing": {
        "code": "OK",
        "message": "Role added successfully"
      }
    }
  }
  ```
</ResponseExample>

## Next steps

<CardGroup>
  <Card title="Remove Scope Role Assignments for Sharing" icon="user-minus" href="/integrations/graphql-api/mutations/dashboard/remove-scope-role-assignments-for-sharing">
    Remove sharing access from users
  </Card>

  <Card title="Create Dashboard" icon="plus" href="/integrations/graphql-api/mutations/dashboard/create-dashboard">
    Create a new Dashboard to share
  </Card>

  <Card title="Dashboard Object" icon="folder" href="/integrations/graphql-api/objects/dashboard">
    Dashboard object schema and properties
  </Card>
</CardGroup>


# Add Widget to Dashboard
Source: https://docs.wisdom.ai/integrations/graphql-api/mutations/dashboard/add-widget-to-dashboard



The `addWidgetToDashboard` mutation adds a new widget to an existing dashboard.

## Signature

```graphql theme={null}
addWidgetToDashboard(id: String!, widget: DashboardWidgetInput!): Dashboard!
```

## Arguments

<ParamField type="String!">
  The unique identifier of the dashboard to add the widget to.
</ParamField>

<ParamField type="DashboardWidgetInput!">
  Widget configuration for the new widget. See [DashboardWidgetInput](/integrations/graphql-api/objects/dashboard-widget-input).
</ParamField>

## Response

Returns the updated `Dashboard` object with the new widget included. See [Dashboard](/integrations/graphql-api/objects/dashboard) for the schema.

## Usage example

The following example shows how to add a new widget to an existing dashboard:

```graphql theme={null}
mutation AddWidgetToDashboard($id: String!, $widget: DashboardWidgetInput!) {
  addWidgetToDashboard(id: $id, widget: $widget) {
    id
    widgets {
      id
      title
      layout {
        top
        left
        width
        height
      }
    }
  }
}
```

<RequestExample>
  ```bash Request theme={null}
  curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <jwt_token>" \
    -d '{
      "query": "mutation AddWidgetToDashboard($id: String!, $widget: DashboardWidgetInput!) { addWidgetToDashboard(id: $id, widget: $widget) { id widgets { id title layout { top left width height } } } }",
      "variables": {
        "id": "dashboard_123456789",
        "widget": {
          "title": "Revenue Trend",
          "nlQuery": "Show revenue trend over time",
          "layout": {
            "top": 4,
            "left": 0,
            "width": 6,
            "height": 4
          }
        }
      }
    }' \
    https://{ACCOUNT}.askwisdom.ai/graphql
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "data": {
      "addWidgetToDashboard": {
        "id": "dashboard_123456789",
        "widgets": [
          {
            "id": "widget_987654321",
            "title": "Revenue Trend",
            "layout": {
              "top": 4,
              "left": 0,
              "width": 6,
              "height": 4
            }
          }
        ]
      }
    }
  }
  ```
</ResponseExample>

## Next steps

<CardGroup>
  <Card title="Update Dashboard Widgets" icon="pen-to-square" href="/integrations/graphql-api/mutations/dashboard/update-dashboard-widgets">
    Update existing widgets
  </Card>

  <Card title="Delete Widget from Dashboard" icon="trash" href="/integrations/graphql-api/mutations/dashboard/delete-widget-from-dashboard">
    Remove widgets from dashboard
  </Card>

  <Card title="DashboardWidgetInput Object" icon="folder" href="/integrations/graphql-api/objects/dashboard-widget-input">
    Widget creation input schema
  </Card>
</CardGroup>


# Create Dashboard
Source: https://docs.wisdom.ai/integrations/graphql-api/mutations/dashboard/create-dashboard



The `createDashboard` mutation creates a new dashboard with the specified configuration and initial widgets.

## Signature

```graphql theme={null}
createDashboard(dashboard: DashboardInput!, widgets: [DashboardWidgetInput!]!): Dashboard!
```

## Arguments

<ParamField type="DashboardInput!">
  Input object containing the dashboard configuration. See [DashboardInput](/integrations/graphql-api/objects/dashboard-input).
</ParamField>

<ParamField type="[DashboardWidgetInput!]!">
  Array of widget configurations to include in the new dashboard. See [DashboardWidgetInput](/integrations/graphql-api/objects/dashboard-widget-input).
</ParamField>

## Response

Returns the newly created `Dashboard` object with all properties populated. See [Dashboard](/integrations/graphql-api/objects/dashboard) for the schema.

## Usage example

The following example shows how to create a new dashboard with initial widgets:

```graphql theme={null}
mutation CreateDashboard($dashboard: DashboardInput!, $widgets: [DashboardWidgetInput!]!) {
  createDashboard(dashboard: $dashboard, widgets: $widgets) {
    id
    name
    description
    widgets {
      id
      title
      layout {
        top
        left
        width
        height
      }
    }
    accessLevel
  }
}
```

<RequestExample>
  ```bash Request theme={null}
  curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <jwt_token>" \
    -d '{
      "query": "mutation CreateDashboard($dashboard: DashboardInput!, $widgets: [DashboardWidgetInput!]!) { createDashboard(dashboard: $dashboard, widgets: $widgets) { id name widgets { id title layout { top left width height } } } }",
      "variables": {
        "dashboard": {
          "name": "Sales Performance Dashboard",
          "description": "Monthly sales metrics and KPIs",
          "domainId": "domain_987654321"
        },
        "widgets": [
          {
            "title": "Total Sales",
            "nlQuery": "What are the total sales?",
            "layout": {
              "top": 0,
              "left": 0,
              "width": 6,
              "height": 4
            }
          }
        ]
      }
    }' \
    https://{ACCOUNT}.askwisdom.ai/graphql
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "data": {
      "createDashboard": {
        "id": "dashboard_123456789",
        "name": "Sales Performance Dashboard",
        "widgets": [
          {
            "id": "widget_987654321",
            "title": "Total Sales",
            "layout": {
              "top": 0,
              "left": 0,
              "width": 6,
              "height": 4
            }
          }
        ]
      }
    }
  }
  ```
</ResponseExample>

## Next steps

<CardGroup>
  <Card title="Update Dashboard" icon="pen-to-square" href="/integrations/graphql-api/mutations/dashboard/update-dashboard">
    Modify dashboard properties
  </Card>

  <Card title="Add Widget to Dashboard" icon="plus" href="/integrations/graphql-api/mutations/dashboard/add-widget-to-dashboard">
    Add widgets to existing dashboard
  </Card>

  <Card title="DashboardInput Object" icon="folder" href="/integrations/graphql-api/objects/dashboard-input">
    Dashboard creation input schema
  </Card>
</CardGroup>


# Delete Dashboard
Source: https://docs.wisdom.ai/integrations/graphql-api/mutations/dashboard/delete-dashboard



The `deleteDashboard` mutation permanently removes a dashboard and all its associated data.

## Signature

```graphql theme={null}
deleteDashboard(id: String!): Boolean!
```

## Arguments

<ParamField type="String!">
  The unique identifier of the dashboard to delete.
</ParamField>

## Response

Returns `true` if the dashboard was successfully deleted, `false` otherwise.

## Usage example

The following example shows how to delete a dashboard:

```graphql theme={null}
mutation DeleteDashboard($id: String!) {
  deleteDashboard(id: $id)
}
```

<RequestExample>
  ```bash Request theme={null}
  curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <jwt_token>" \
    -d '{
      "query": "mutation DeleteDashboard($id: String!) { deleteDashboard(id: $id) }",
      "variables": {
        "id": "dashboard_123456789"
      }
    }' \
    https://{ACCOUNT}.askwisdom.ai/graphql
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "data": {
      "deleteDashboard": true
    }
  }
  ```
</ResponseExample>

## Next steps

<CardGroup>
  <Card title="Dashboards Query" icon="list" href="/integrations/graphql-api/queries/dashboard/dashboards">
    List available dashboards
  </Card>
</CardGroup>


# Delete Widget from Dashboard
Source: https://docs.wisdom.ai/integrations/graphql-api/mutations/dashboard/delete-widget-from-dashboard



The `deleteWidgetFromDashboard` mutation removes a specific widget from a dashboard.

## Signature

```graphql theme={null}
deleteWidgetFromDashboard(id: String!, widgetId: String!): Dashboard!
```

## Arguments

<ParamField type="String!">
  The unique identifier of the dashboard containing the widget.
</ParamField>

<ParamField type="String!">
  The unique identifier of the widget to remove from the dashboard.
</ParamField>

## Response

Returns the updated `Dashboard` object with the widget removed. See [Dashboard](/integrations/graphql-api/objects/dashboard) for the schema.

## Usage example

The following example shows how to remove a widget from a dashboard:

```graphql theme={null}
mutation DeleteWidgetFromDashboard($id: String!, $widgetId: String!) {
  deleteWidgetFromDashboard(id: $id, widgetId: $widgetId) {
    id
    widgets {
      id
      title
    }
  }
}
```

<RequestExample>
  ```bash Request theme={null}
  curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <jwt_token>" \
    -d '{
      "query": "mutation DeleteWidgetFromDashboard($id: String!, $widgetId: String!) { deleteWidgetFromDashboard(id: $id, widgetId: $widgetId) { id widgets { id title } } }",
      "variables": {
        "id": "dashboard_123456789",
        "widgetId": "widget_987654321"
      }
    }' \
    https://{ACCOUNT}.askwisdom.ai/graphql
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "data": {
      "deleteWidgetFromDashboard": {
        "id": "dashboard_123456789",
        "widgets": [
          {
            "id": "widget_remaining",
            "title": "Remaining Widget"
          }
        ]
      }
    }
  }
  ```
</ResponseExample>

## Next steps

<CardGroup>
  <Card title="Add Widget to Dashboard" icon="plus" href="/integrations/graphql-api/mutations/dashboard/add-widget-to-dashboard">
    Add widgets to dashboard
  </Card>

  <Card title="Update Dashboard Widgets" icon="pen-to-square" href="/integrations/graphql-api/mutations/dashboard/update-dashboard-widgets">
    Update existing widgets
  </Card>
</CardGroup>


# Refresh Dashboard
Source: https://docs.wisdom.ai/integrations/graphql-api/mutations/dashboard/refresh-dashboard



The `refreshDashboard` mutation refreshes all data in a dashboard's widgets to show the latest information.

## Signature

```graphql theme={null}
refreshDashboard(id: String!, version: String): Dashboard!
```

## Arguments

<ParamField type="String!">
  The unique identifier of the dashboard to refresh.
</ParamField>

## Response

Returns the refreshed `Dashboard` object with updated widget data. See [Dashboard](/integrations/graphql-api/objects/dashboard) for the schema.

## Usage example

The following example shows how to refresh all dashboard data:

```graphql theme={null}
mutation RefreshDashboard($id: String!) {
  refreshDashboard(id: $id) {
    id
    widgets {
      id
      title
      dataRefreshedAt
    }
  }
}
```

<RequestExample>
  ```bash Request theme={null}
  curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <jwt_token>" \
    -d '{
      "query": "mutation RefreshDashboard($id: String!) { refreshDashboard(id: $id) { id widgets { id title dataRefreshedAt } } }",
      "variables": {
        "id": "dashboard_123456789"
      }
    }' \
    https://{ACCOUNT}.askwisdom.ai/graphql
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "data": {
      "refreshDashboard": {
        "id": "dashboard_123456789",
        "widgets": [
          {
            "id": "widget_987654321",
            "title": "Sales Chart",
            "dataRefreshedAt": "2024-01-15T10:30:00Z"
          }
        ]
      }
    }
  }
  ```
</ResponseExample>

## Next steps

<CardGroup>
  <Card title="Dashboard Query" icon="magnifying-glass" href="/integrations/graphql-api/queries/dashboard/dashboard">
    Retrieve refreshed dashboard data
  </Card>
</CardGroup>


# Remove Scope Role Assignments for Sharing
Source: https://docs.wisdom.ai/integrations/graphql-api/mutations/dashboard/remove-scope-role-assignments-for-sharing



The `removeScopeRoleAssignmentsForSharing` mutation removes access to a specific resource (like a Dashboard) by revoking roles from users. This allows you to stop sharing Dashboards with individuals or groups.

## Signature

```graphql theme={null}
removeScopeRoleAssignmentsForSharing(
  scopeId: ID!
  scopeRoleAssignments: [ScopeRoleAssignmentInput!]!
  scopeType: ScopeType!
): ResponseStatus!
```

## Arguments

<ParamField type="ID!">
  The unique identifier of the resource you want to remove sharing from (e.g., a Dashboard ID).
</ParamField>

<ParamField type="[ScopeRoleAssignmentInput!]!">
  Array of user-role assignments to remove. See [ScopeRoleAssignmentInput](/integrations/graphql-api/objects/scope-role-assignment-input) for the input structure.
</ParamField>

<ParamField type="ScopeType!">
  The type of resource being unshared. For Dashboards, this should be `DASHBOARD`.
</ParamField>

## Response

Returns a `ResponseStatus` object indicating the success or failure of the operation:

```json theme={null}
{
  "code": "OK",
  "message": "Role removed successfully"
}
```

## Usage example

The following example shows how to remove sharing access from a colleague:

```graphql theme={null}
mutation RemoveScopeRoleAssignments($scopeId: ID!, $scopeRoleAssignments: [ScopeRoleAssignmentInput!]!, $scopeType: ScopeType!) {
  removeScopeRoleAssignmentsForSharing(
    scopeId: $scopeId
    scopeRoleAssignments: $scopeRoleAssignments
    scopeType: $scopeType
  ) {
    code
    message
  }
}
```

<RequestExample>
  ```bash Request theme={null}
  curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <jwt_token>" \
    -d '{
      "query": "mutation RemoveScopeRoleAssignments($scopeId: ID!, $scopeRoleAssignments: [ScopeRoleAssignmentInput!]!, $scopeType: ScopeType!) { removeScopeRoleAssignmentsForSharing(scopeId: $scopeId, scopeRoleAssignments: $scopeRoleAssignments, scopeType: $scopeType) { code message } }",
      "variables": {
        "scopeId": "story_123456789",
        "scopeRoleAssignments": [
          {
            "roleId": "00000000-0000-0000-0000-000000000009",
            "principalId": "user_987654321"
          }
        ],
        "scopeType": "DASHBOARD"
      }
    }' \
    https://{ACCOUNT}.askwisdom.ai/graphql
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "data": {
      "removeScopeRoleAssignmentsForSharing": {
        "code": "OK",
        "message": "Role removed successfully"
      }
    }
  }
  ```
</ResponseExample>

## Next steps

<CardGroup>
  <Card title="Add Scope Role Assignments for Sharing" icon="user-plus" href="/integrations/graphql-api/mutations/dashboard/add-scope-role-assignments-for-sharing">
    Grant sharing access to users
  </Card>

  <Card title="Delete Dashboard" icon="trash" href="/integrations/graphql-api/mutations/dashboard/delete-dashboard">
    Permanently delete a Dashboard
  </Card>

  <Card title="Dashboard Object" icon="folder" href="/integrations/graphql-api/objects/dashboard">
    Dashboard object schema and properties
  </Card>
</CardGroup>


# Update Dashboard
Source: https://docs.wisdom.ai/integrations/graphql-api/mutations/dashboard/update-dashboard



The `updateDashboard` mutation modifies the properties of an existing dashboard.

## Signature

```graphql theme={null}
updateDashboard(id: String!, dashboard: DashboardInput): Dashboard!
```

## Arguments

<ParamField type="String!">
  The unique identifier of the dashboard to update.
</ParamField>

<ParamField type="DashboardInput">
  Input object containing the updated dashboard properties. See [DashboardInput](/integrations/graphql-api/objects/dashboard-input).
</ParamField>

## Response

Returns the updated `Dashboard` object with all properties populated. See [Dashboard](/integrations/graphql-api/objects/dashboard) for the schema.

## Usage example

The following example shows how to update a dashboard's name and description:

```graphql theme={null}
mutation UpdateDashboard($id: String!, $dashboard: DashboardInput!) {
  updateDashboard(id: $id, dashboard: $dashboard) {
    id
    name
    description
    widgets {
      id
      title
    }
  }
}
```

<RequestExample>
  ```bash Request theme={null}
  curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <jwt_token>" \
    -d '{
      "query": "mutation UpdateDashboard($id: String!, $dashboard: DashboardInput!) { updateDashboard(id: $id, dashboard: $dashboard) { id name description } }",
      "variables": {
        "id": "dashboard_123456789",
        "dashboard": {
          "name": "Updated Sales Dashboard",
          "description": "Updated monthly sales metrics and KPIs"
        }
      }
    }' \
    https://{ACCOUNT}.askwisdom.ai/graphql
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "data": {
      "updateDashboard": {
        "id": "dashboard_123456789",
        "name": "Updated Sales Dashboard",
        "description": "Updated monthly sales metrics and KPIs"
      }
    }
  }
  ```
</ResponseExample>

## Next steps

<CardGroup>
  <Card title="Create Dashboard" icon="plus" href="/integrations/graphql-api/mutations/dashboard/create-dashboard">
    Create a new dashboard
  </Card>

  <Card title="Update Dashboard Widgets" icon="pen-to-square" href="/integrations/graphql-api/mutations/dashboard/update-dashboard-widgets">
    Update dashboard widgets
  </Card>

  <Card title="DashboardInput Object" icon="folder" href="/integrations/graphql-api/objects/dashboard-input">
    Dashboard update input schema
  </Card>
</CardGroup>


# Update Dashboard Filters
Source: https://docs.wisdom.ai/integrations/graphql-api/mutations/dashboard/update-dashboard-filters



The `updateDashboardFilters` mutation applies filter changes to a dashboard and updates all affected widgets.

## Signature

```graphql theme={null}
updateDashboardFilters(id: String!, version: String, filterMutations: FilterMutationInput!): Dashboard!
```

## Arguments

<ParamField type="String!">
  The unique identifier of the dashboard to update filters for.
</ParamField>

<ParamField type="FilterMutationInput!">
  Filter mutation configuration specifying the changes to apply (`FilterMutationInput`).
</ParamField>

## Response

Returns the updated `Dashboard` object with refreshed filter definitions. See [Dashboard](/integrations/graphql-api/objects/dashboard) for the schema.

## Usage example

The following example shows how to apply filter changes to a dashboard:

```graphql theme={null}
mutation UpdateDashboardFilters($id: String!, $filterMutations: FilterMutationInput!) {
  updateDashboardFilters(id: $id, filterMutations: $filterMutations) {
    id
    filters {
      id
      parsedFilter {
        column
        value
      }
      appliedState {
        widgetId
        filterIdOnWidget
      }
    }
  }
}
```

<RequestExample>
  ```bash Request theme={null}
  curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <jwt_token>" \
    -d '{
      "query": "mutation UpdateDashboardFilters($id: String!, $filterMutations: FilterMutationInput!) { updateDashboardFilters(id: $id, filterMutations: $filterMutations) { id filters { id parsedFilter { column value } } } }",
      "variables": {
        "id": "dashboard_123456789",
        "filterMutations": {
          "addFilters": [
            {
              "column": "region",
              "value": "North America"
            }
          ]
        }
      }
    }' \
    https://{ACCOUNT}.askwisdom.ai/graphql
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "data": {
      "updateDashboardFilters": {
        "id": "dashboard_123456789",
        "filters": [
          {
            "id": "filter_987654321",
            "parsedFilter": {
              "column": "region",
              "value": "North America"
            }
          }
        ]
      }
    }
  }
  ```
</ResponseExample>

## Next steps

<CardGroup>
  <Card title="Dashboard Query" icon="magnifying-glass" href="/integrations/graphql-api/queries/dashboard/dashboard">
    Retrieve dashboard with updated filters
  </Card>

  <Card title="DashboardFilterDefinition Object" icon="filter" href="/integrations/graphql-api/objects/dashboard-filter-definition">
    Filter definition schema
  </Card>
</CardGroup>


# Update Dashboard Widgets
Source: https://docs.wisdom.ai/integrations/graphql-api/mutations/dashboard/update-dashboard-widgets



The `updateDashboardWidgets` mutation updates multiple existing widgets on a dashboard in a single operation. This allows for bulk updates to widget properties such as titles, layouts, and other configurations.

## Signature

```graphql theme={null}
updateDashboardWidgets(widgets: [DashboardWidgetInput!]): Dashboard!
```

## Arguments

<ParamField type="[DashboardWidgetInput!]!">
  Array of widget input objects containing the updates to apply. Each widget must include an `id` field to identify which widget to update. See [DashboardWidgetInput](/integrations/graphql-api/objects/dashboard-widget-input) for the complete schema.
</ParamField>

## Response

Returns the updated `Dashboard` object with all widgets populated, including the updated widget configurations. See [Dashboard](/integrations/graphql-api/objects/dashboard) for the schema.

## Usage example

The following example shows how to update multiple widget properties on a dashboard:

```graphql theme={null}
mutation UpdateDashboardWidgets($widgets: [DashboardWidgetInput!]) {
  updateDashboardWidgets(widgets: $widgets) {
    id
    version
    name
    widgets {
      id
      title
      nlQuery
      layout {
        top
        left
        width
        height
      }
      widgetType
    }
  }
}
```

<RequestExample>
  ```bash Request theme={null}
  curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <jwt_token>" \
    -d '{
      "query": "mutation UpdateDashboardWidgets($widgets: [DashboardWidgetInput!]) { updateDashboardWidgets(widgets: $widgets) { id version name widgets { id title nlQuery layout { top left width height } widgetType } } }",
      "variables": {
        "widgets": [
          {
            "id": "widget_123456789",
            "title": "Updated Revenue Chart",
            "nlQuery": "Show monthly revenue by region"
          },
          {
            "id": "widget_987654321",
            "layout": {
              "top": 6,
              "left": 4,
              "width": 8,
              "height": 6
            }
          }
        ]
      }
    }' \
    https://{ACCOUNT}.askwisdom.ai/graphql
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "data": {
      "updateDashboardWidgets": {
        "id": "dashboard_abcdef123456",
        "version": "v1.2",
        "name": "Sales Dashboard",
        "widgets": [
          {
            "id": "widget_123456789",
            "title": "Updated Revenue Chart",
            "nlQuery": "Show monthly revenue by region",
            "layout": {
              "top": 0,
              "left": 0,
              "width": 6,
              "height": 4
            },
            "widgetType": "WIDGET_TYPE_VISUALIZATION"
          },
          {
            "id": "widget_987654321",
            "title": "Customer Count",
            "nlQuery": "Total customers",
            "layout": {
              "top": 6,
              "left": 4,
              "width": 8,
              "height": 6
            },
            "widgetType": "WIDGET_TYPE_SUMMARY"
          }
        ]
      }
    }
  }
  ```
</ResponseExample>

## Next steps

<CardGroup>
  <Card title="Add Widget to Dashboard" icon="plus" href="/integrations/graphql-api/mutations/dashboard/add-widget-to-dashboard">
    Add a new widget to dashboard
  </Card>

  <Card title="Delete Widget from Dashboard" icon="trash" href="/integrations/graphql-api/mutations/dashboard/delete-widget-from-dashboard">
    Remove widgets from dashboard
  </Card>

  <Card title="Update Dashboard" icon="pen-to-square" href="/integrations/graphql-api/mutations/dashboard/update-dashboard">
    Update dashboard properties
  </Card>

  <Card title="DashboardWidgetInput Object" icon="folder" href="/integrations/graphql-api/objects/dashboard-widget-input">
    Widget input schema
  </Card>
</CardGroup>


# Create Domain
Source: https://docs.wisdom.ai/integrations/graphql-api/mutations/domain/create-domain



The `createDomain` mutation creates a new domain with a name and optional description.

## Signature

```graphql theme={null}
createDomain(input: CreateDomainInput!): DomainModel!
```

<Note>
  This mutation can only be executed by an administrator or a data administrator of the specific domain ID.
</Note>

## Arguments

<ParamField type="CreateDomainInput!">
  Input object containing domain creation parameters. See [CreateDomainInput](#createdomaininput).
</ParamField>

### CreateDomainInput

<ParamField type="String!">
  The name of the domain. Must be unique within your organization.
</ParamField>

<ParamField type="String">
  Optional description explaining the purpose and contents of the domain.
</ParamField>

<ParamField type="ID">
  The workspace ID in which to create the domain. Defaults to the current workspace if not specified.
</ParamField>

## Response

Returns a `DomainModel` object representing the newly created domain. See [DomainModel](/integrations/graphql-api/objects/domain-model) for the schema.

## Usage example

Create a domain for organizing sales-related data sources:

```graphql theme={null}
mutation CreateDomain($input: CreateDomainInput!) {
  createDomain(input: $input) {
    id
    version
    name
    description
  }
}
```

<RequestExample>
  ```bash Request theme={null}
  curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <jwt_token>" \
    -d '{
      "query": "mutation CreateDomain($input: CreateDomainInput!) { createDomain(input: $input) { id name description } }",
      "variables": {
        "input": {
          "name": "Sales Analytics",
          "description": "Customer data, transactions, and sales performance metrics"
        }
      }
    }' \
    https://{ACCOUNT}.askwisdom.ai/graphql
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "data": {
      "createDomain": {
        "id": "ET_DOMAIN_id-here",
        "name": "Sales Analytics",
        "description": "Customer data, transactions, and sales performance metrics"
      }
    }
  }
  ```
</ResponseExample>

## Related operation

<CardGroup>
  <Card title="DomainModel Schema" icon="folder" href="/integrations/graphql-api/objects/domain-model">
    Learn about domain structure and properties
  </Card>
</CardGroup>


# Duplicate Domain
Source: https://docs.wisdom.ai/integrations/graphql-api/mutations/domain/duplicate-domain



The `duplicateDomain` mutation duplicates (clones) an existing domain, creating an independent copy.

## Signature

```graphql theme={null}
duplicateDomain(id: ID!, workspaceID: ID): DomainModel!
```

<Note>
  This mutation requires write permission (`zsheet:write`) on the source domain.
</Note>

## Arguments

<ParamField type="ID!">
  The ID of the source domain to duplicate.
</ParamField>

<ParamField type="ID">
  The target workspace ID where the duplicate domain will be created. Defaults to the current workspace if not specified.
</ParamField>

## Response

Returns a `DomainModel` object representing the newly created duplicate domain. See [DomainModel](/integrations/graphql-api/objects/domain-model) for the schema.

## Usage example

Duplicate a domain into the current workspace:

```graphql theme={null}
mutation DuplicateDomain($id: ID!, $workspaceID: ID) {
  duplicateDomain(id: $id, workspaceID: $workspaceID) {
    id
    version
    name
    description
  }
}
```

<RequestExample>
  ```bash Request theme={null}
  curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <jwt_token>" \
    -d '{
      "query": "mutation DuplicateDomain($id: ID!, $workspaceID: ID) { duplicateDomain(id: $id, workspaceID: $workspaceID) { id name description } }",
      "variables": {
        "id": "ET_DOMAIN_id-here",
        "workspaceID": "ET_WORKSPACE_id-here"
      }
    }' \
    https://{ACCOUNT}.askwisdom.ai/graphql
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "data": {
      "duplicateDomain": {
        "id": "ET_DOMAIN_new-id-here",
        "name": "Sales Analytics (Copy)",
        "description": "Customer data, transactions, and sales performance metrics"
      }
    }
  }
  ```
</ResponseExample>

## Related operation

<CardGroup>
  <Card title="DomainModel Schema" icon="folder" href="/integrations/graphql-api/objects/domain-model">
    Learn about domain structure and properties
  </Card>

  <Card title="Create Domain" icon="plus" href="/integrations/graphql-api/mutations/domain/create-domain">
    Create a new domain from scratch
  </Card>
</CardGroup>


# Update Data Sources
Source: https://docs.wisdom.ai/integrations/graphql-api/mutations/domain/update-data-sources



The `dataSourcesUpdate` mutation updates the data sources configuration for an existing domain by specifying tables and their relationships. This operation allows you to modify which tables are included in a domain and how they are connected through joins.

<Note>
  The input will overwrite any existing data sources that already existed. Treat the input as what the updated state of data sources should look like.
</Note>

## Signature

```graphql theme={null}
dataSourcesUpdate(input: DataSourcesUpdateInput!): DataSourcesUpdatePayload!
```

<Note>
  This mutation can only be executed by an administrator or a data administrator of the specific connection ID.
</Note>

## Arguments

<ParamField type="DataSourcesUpdateInput!">
  Input object containing data sources update parameters. See [DataSourcesUpdateInput](#datasourcesupdateinput).
</ParamField>

### DataSourcesUpdateInput

<ParamField type="ID!">
  The unique identifier of the domain to update.
</ParamField>

<ParamField type="[TableInput!]!">
  List of tables to include in the domain. See [TableInput](/integrations/graphql-api/objects/table-input).
</ParamField>

<ParamField type="[JoinInput!]">
  List of join relationships between tables. See [JoinInput](/integrations/graphql-api/objects/join-input).
</ParamField>

## Response

Returns a `DataSourcesUpdatePayload` object containing:

<ParamField type="String">
  Error, if any occurred. `null` indicates success.
</ParamField>

<ParamField type="Boolean!">
  Whether the update operation completed successfully.
</ParamField>

## Usage example

Update a domain's data sources with tables and their relationships:

```graphql theme={null}
mutation UpdateDataSources($input: DataSourcesUpdateInput!) {
  dataSourcesUpdate(input: $input) {
    success
    error
  }
}
```

<RequestExample>
  ```bash Request theme={null}
  curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <jwt_token>" \
    -d '{
      "query": "mutation UpdateDataSources($input: DataSourcesUpdateInput!) { dataSourcesUpdate(input: $input) { success error } }",
      "variables": {
        "input": {
          "domainId": "ET_DOMAIN_id-here",
          "tables": [
            {
              "connection_id": "et-connection-id-here",
              "database_name": "analytics_warehouse",
              "schema_name": "customer_intelligence",
              "table_name": "user_accounts"
            },
            {
              "connection_id": "et-connection-id2-here",
              "database_name": "analytics_warehouse",
              "schema_name": "business_metrics",
              "table_name": "subscription_events"
            }
          ],
          "joins": [
            {
              "leftTable": "user_accounts",
              "rightTable": "subscription_events",
              "relationshipType": "ONE_TO_MANY",
              "joinConditions": [
                {
                  "leftColumnName": "account_id",
                  "rightColumnName": "account_id"
                }
              ]
            }
          ]
        }
      }
    }' \
    https://{ACCOUNT}.askwisdom.ai/graphql
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "data": {
      "dataSourcesUpdate": {
        "success": true,
        "error": null
      }
    }
  }
  ```
</ResponseExample>

## Next steps

<CardGroup>
  <Card title="Create Domain" icon="plus" href="/integrations/graphql-api/mutations/domain/create-domain">
    Create new domains for organizing data sources
  </Card>

  <Card title="TableInput Schema" icon="table" href="/integrations/graphql-api/objects/table-input">
    Learn about table input structure and validation
  </Card>

  <Card title="JoinInput Schema" icon="link" href="/integrations/graphql-api/objects/join-input">
    Understand join configuration and relationship types
  </Card>

  <Card title="DomainModel Schema" icon="folder" href="/integrations/graphql-api/objects/domain-model">
    Explore domain structure and properties
  </Card>
</CardGroup>


# Create Users
Source: https://docs.wisdom.ai/integrations/graphql-api/mutations/user/create-users



The `createUsers` mutation provisions one or more users in a workspace. Call this before impersonating a user in the embedded flow — a user must exist before they can be impersonated.

## Signature

```graphql theme={null}
createUsers(input: CreateUsersInput!): CreateUsersResponse!
```

## Arguments

<ParamField type="CreateUsersInput!">
  Input object containing the details for the users to create.
</ParamField>

### CreateUsersInput fields

<ParamField type="[String!]!">
  One or more email addresses to provision. User matching is email-based — each email must be unique within the workspace.

  <Note>
    If your embedded users may share email addresses across tenants (e.g., the same person is a customer of multiple clients), append a unique identifier to the email prefix: `alice+tenant123@yourcompany.com`. This prevents cross-tenant session collisions.
  </Note>
</ParamField>

<ParamField type="ID">
  The workspace to create the users in. Required for multi-workspace deployments.
</ParamField>

<ParamField type="[RoleAssignmentInput!]">
  Role assignments for the new users. Each entry specifies a `roleId` and `scopes` (`RoleAssignmentInput`).

  For embedded dashboards, assign the Viewer role to hide edit controls:

  ```json theme={null}
  [{ "roleId": "00000000-0000-0000-0000-000000000003", "scopes": ["{{DOMAIN_ID}}"] }]
  ```
</ParamField>

<ParamField type="Boolean">
  Whether to send a welcome email to the new users. Default: `false`. Set to `false` for programmatically provisioned embedded users.
</ParamField>

<ParamField type="[UserAttributeInput!]">
  Key-value pairs for parameterized connections and row-level data access. These are stored as DATABASE-sourced attributes. See [User attributes](/integrations/user-management/user-attributes).
</ParamField>

<ParamField type="[ID!]">
  Optional group IDs to assign the users to on creation.
</ParamField>

<Note>
  `CreateUsersInput` does not include a display name field. Users provisioned via this mutation appear as their email address in the WisdomAI admin screen. If a display name is needed, pass it as a `userAttributes` entry (for example, `{ "key": "display_name", "value": "Alice Smith" }`).
</Note>

## Response

<ParamField type="ResponseStatus!">
  Indicates whether the operation succeeded. See [ResponseStatus](/integrations/graphql-api/objects/response-status).

  <Info>
    The `status` field here returns a `ResponseStatus` object (with `code` and `message`). This is distinct from the `UserStatus` enum (e.g., `ACTIVE`) found on the `User` object.
  </Info>
</ParamField>

## Usage example

```graphql theme={null}
mutation CreateUsers($input: CreateUsersInput!) {
  createUsers(input: $input) {
    status {
      code
      message
    }
  }
}
```

<RequestExample>
  ```bash Single user theme={null}
  curl -s -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <access_token>" \
    -d '{
      "query": "mutation CreateUsers($input: CreateUsersInput!) { createUsers(input: $input) { status { code message } } }",
      "variables": {
        "input": {
          "emails": ["alice@yourcompany.com"],
          "workspaceID": "workspace_123",
          "roleAssignments": [{ "roleId": "00000000-0000-0000-0000-000000000003", "scopes": ["{{DOMAIN_ID}}"] }],
          "sendWelcomeEmail": false
        }
      }
    }' \
    https://{ACCOUNT}.askwisdom.ai/graphql
  ```

  ```bash Multiple users theme={null}
  curl -s -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <access_token>" \
    -d '{
      "query": "mutation CreateUsers($input: CreateUsersInput!) { createUsers(input: $input) { status { code message } } }",
      "variables": {
        "input": {
          "emails": ["alice@yourcompany.com", "bob@yourcompany.com"],
          "workspaceID": "workspace_123",
          "roleAssignments": [{ "roleId": "00000000-0000-0000-0000-000000000003", "scopes": ["{{DOMAIN_ID}}"] }],
          "sendWelcomeEmail": false
        }
      }
    }' \
    https://{ACCOUNT}.askwisdom.ai/graphql
  ```

  ```bash With user attributes theme={null}
  curl -s -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <access_token>" \
    -d '{
      "query": "mutation CreateUsers($input: CreateUsersInput!) { createUsers(input: $input) { status { code message } } }",
      "variables": {
        "input": {
          "emails": ["alice@yourcompany.com"],
          "workspaceID": "workspace_123",
          "roleAssignments": [{ "roleId": "00000000-0000-0000-0000-000000000003", "scopes": ["{{DOMAIN_ID}}"] }],
          "sendWelcomeEmail": false,
          "userAttributes": [
            { "key": "account_id", "value": "acct_456" },
            { "key": "region", "value": "us-east" }
          ]
        }
      }
    }' \
    https://{ACCOUNT}.askwisdom.ai/graphql
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "data": {
      "createUsers": {
        "status": {
          "code": "OK",
          "message": "Users created successfully"
        }
      }
    }
  }
  ```
</ResponseExample>

<Warning>
  If a user with the same email already exists, the call succeeds but re-applies the role assignments you pass in, overwriting any manually assigned roles. To avoid resetting roles on existing users, check [`listUsers`](/integrations/graphql-api/queries/user/list-users) first and skip `createUsers` for users already provisioned.
</Warning>

## Related articles

<CardGroup>
  <Card title="Set user attributes" icon="tag" href="/integrations/graphql-api/mutations/user/set-user-attributes">
    Update attributes on existing users
  </Card>

  <Card title="Impersonate user" icon="user-secret" href="/integrations/graphql-api/mutations/auth/impersonate-user">
    Generate a session JWT for the created user
  </Card>

  <Card title="User attributes" icon="list" href="/integrations/user-management/user-attributes">
    How attributes control data access
  </Card>

  <Card title="Embedding overview" icon="code" href="/integrations/embeddings/embedding">
    Full server-side embedding flow
  </Card>
</CardGroup>


# Delete Users From Workspace
Source: https://docs.wisdom.ai/integrations/graphql-api/mutations/user/delete-users-from-workspace



The `deleteUsersFromWorkspace` mutation removes one or more users from a workspace.

<Warning>
  This action is **irreversible**. Deleted users lose all role assignments, attributes, and access to the workspace. Make sure you have the correct user IDs before calling this mutation.
</Warning>

## Signature

```graphql theme={null}
deleteUsersFromWorkspace(ids: [ID!]!, workspaceID: ID!): DeleteUsersFromWorkspaceResponse!
```

## Arguments

<ParamField type="[ID!]!">
  The IDs of the users to delete. Use [listUsers](/integrations/graphql-api/queries/user/list-users) to find user IDs.
</ParamField>

<ParamField type="ID!">
  The workspace to remove the users from.
</ParamField>

## Permissions

Requires `iam:delete` scoped to the target workspace.

## Response

<ParamField type="ResponseStatus!">
  Indicates whether the operation succeeded. See [ResponseStatus](/integrations/graphql-api/objects/response-status).
</ParamField>

## Usage example

```graphql theme={null}
mutation DeleteUsersFromWorkspace($ids: [ID!]!, $workspaceID: ID!) {
  deleteUsersFromWorkspace(ids: $ids, workspaceID: $workspaceID) {
    status {
      code
      message
    }
  }
}
```

<RequestExample>
  ```bash Request theme={null}
  curl -s -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <access_token>" \
    -d '{
      "query": "mutation DeleteUsersFromWorkspace($ids: [ID!]!, $workspaceID: ID!) { deleteUsersFromWorkspace(ids: $ids, workspaceID: $workspaceID) { status { code message } } }",
      "variables": {
        "ids": ["user_abc123", "user_def456"],
        "workspaceID": "workspace_123"
      }
    }' \
    https://{ACCOUNT}.askwisdom.ai/graphql
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "data": {
      "deleteUsersFromWorkspace": {
        "status": {
          "code": "OK",
          "message": "Users deleted successfully"
        }
      }
    }
  }
  ```
</ResponseExample>

## Related articles

<CardGroup>
  <Card title="List users" icon="users" href="/integrations/graphql-api/queries/user/list-users">
    Query users before deleting them
  </Card>

  <Card title="Create users" icon="user-plus" href="/integrations/graphql-api/mutations/user/create-users">
    Provision new users in a workspace
  </Card>
</CardGroup>


# Set User Attributes
Source: https://docs.wisdom.ai/integrations/graphql-api/mutations/user/set-user-attributes



The `setUserAttributes` mutation updates the DATABASE-sourced attributes for an existing user. Use this to update persistent key-value pairs that control parameterized connections and row-level data access.

<Warning>
  This mutation **replaces all DATABASE-sourced attributes** on the user. Any attributes not included in the new list will be removed. JWT-sourced attributes (from SSO claims) are not affected. See [User attributes](/integrations/user-management/user-attributes) for the difference between attribute sources.
</Warning>

## Signature

```graphql theme={null}
setUserAttributes(input: SetUserAttributesInput!): SetUserAttributesResponse!
```

## Arguments

<ParamField type="SetUserAttributesInput!">
  Input object identifying the user and the new attribute set.
</ParamField>

### SetUserAttributesInput fields

<ParamField type="ID!">
  The ID of the user whose attributes should be updated. Use [listUsers](/integrations/graphql-api/queries/user/list-users) to find user IDs.
</ParamField>

<ParamField type="[UserAttributeInput!]!">
  The complete new set of DATABASE-sourced attributes. This replaces all existing DATABASE-sourced attributes — include every attribute you want the user to have after the call, not just the ones you're changing.
</ParamField>

## Response

<ParamField type="ResponseStatus!">
  Indicates whether the operation succeeded. See [ResponseStatus](/integrations/graphql-api/objects/response-status).
</ParamField>

## Usage example

```graphql theme={null}
mutation SetUserAttributes($input: SetUserAttributesInput!) {
  setUserAttributes(input: $input) {
    status {
      code
      message
    }
  }
}
```

<RequestExample>
  ```bash Request theme={null}
  curl -s -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <access_token>" \
    -d '{
      "query": "mutation SetUserAttributes($input: SetUserAttributesInput!) { setUserAttributes(input: $input) { status { code message } } }",
      "variables": {
        "input": {
          "userId": "user_abc123",
          "userAttributes": [
            { "key": "account_id", "value": "acct_456" },
            { "key": "region", "value": "us-west" }
          ]
        }
      }
    }' \
    https://{ACCOUNT}.askwisdom.ai/graphql
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "data": {
      "setUserAttributes": {
        "status": {
          "code": "OK",
          "message": "User attributes updated successfully"
        }
      }
    }
  }
  ```
</ResponseExample>

<Tip>
  For attributes that are stable (e.g., `account_id`), set them once at creation via `userAttributes` in [createUsers](/integrations/graphql-api/mutations/user/create-users). For session-scoped overrides that should not be persisted, use `attributes` in [impersonateUser](/integrations/graphql-api/mutations/auth/impersonate-user) instead.
</Tip>

## Related articles

<CardGroup>
  <Card title="User attributes" icon="list" href="/integrations/user-management/user-attributes">
    Understand attribute sources and how they interact
  </Card>

  <Card title="Impersonate user" icon="user-secret" href="/integrations/graphql-api/mutations/auth/impersonate-user">
    Pass transient attributes at session time
  </Card>

  <Card title="List users" icon="users" href="/integrations/graphql-api/queries/user/list-users">
    Query users and inspect their current attributes
  </Card>
</CardGroup>


# AIWorkstream
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/ai-workstream



This page describes the information and status fields available for AI workflows.

## AIWorkstream

<ParamField type="String!">
  Unique identifier for the AI workstream.
</ParamField>

<ParamField type="String!">
  Current status of the AI workflow.
</ParamField>

<ParamField type="Float">
  Progress percentage of the workflow (0-100).
</ParamField>

<ParamField type="[WorkflowStep!]">
  Array of workflow steps and their status.
</ParamField>

<ParamField type="JSON">
  Additional metadata about the workflow.
</ParamField>

## Related operation

<CardGroup>
  <Card title="DeltaElement Schema" icon="cube" href="/integrations/graphql-api/objects/delta-element">
    Container for AI workstreams
  </Card>
</CardGroup>


# Attributes
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/attributes



This page describes the formatting options and metadata attributes you can use when defining operations.

## Attributes

<ParamField type="Boolean">
  Whether the content should be formatted as code.
</ParamField>

<ParamField type="Boolean">
  Whether the content ends with a line break.
</ParamField>

<ParamField type="Boolean">
  Whether the content represents an error state.
</ParamField>

<ParamField type="Boolean">
  Whether the content shows progress information.
</ParamField>

<ParamField type="Boolean">
  Whether the content is subtext or secondary information.
</ParamField>

<ParamField type="String">
  SQL dialect for code formatting.
</ParamField>

<ParamField type="String">
  Container identifier for grouping content.
</ParamField>

<ParamField type="String">
  Query being generated (for progress indication).
</ParamField>

<ParamField type="String">
  Timestamp of the last update.
</ParamField>

<ParamField type="String">
  Stream identifier for real-time content.
</ParamField>

<ParamField type="String">
  Name of derived table (for SQL content).
</ParamField>

<ParamField type="String">
  Tool that generated this content.
</ParamField>

<ParamField type="Boolean">
  Whether the content represents an insight.
</ParamField>

<ParamField type="Boolean">
  Whether the content is a domain modeling suggestion.
</ParamField>

<ParamField type="ReportAttributes">
  Report-specific attributes for content.
</ParamField>

## ReportAttributes

<ParamField type="String">
  Identifier for the associated report.
</ParamField>

<ParamField type="Boolean">
  Whether this is an intermediate step in report generation.
</ParamField>

<ParamField type="Boolean">
  Whether this is a report element.
</ParamField>

<ParamField type="Boolean">
  Whether this is a report title.
</ParamField>

## Related operation

<CardGroup>
  <Card title="Operation Schema" icon="gear" href="/integrations/graphql-api/objects/operation">
    Operations using attributes
  </Card>
</CardGroup>


# CanvasConfig
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/canvas-config



This page describes the CanvasConfig object that represents the schema for domain canvas configuration.

## CanvasConfig

<ParamField type="Boolean!">
  Whether to disable suggested questions on the canvas.
</ParamField>

<ParamField type="Boolean!">
  Whether to enable admin V2 access for this domain.
</ParamField>

<ParamField type="Boolean!">
  Whether to force insights generation for queries.
</ParamField>

## Related operations

<CardGroup>
  <Card title="DomainModel Object" icon="folder" href="/integrations/graphql-api/objects/domain-model">
    Parent domain structure
  </Card>
</CardGroup>


# ChatMessage
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/chat-message



This page describes the complete message structure used in conversations.

## ChatMessage

<ParamField type="ID!">
  Unique identifier for the chat message.
</ParamField>

<ParamField type="Delta!">
  The content of the message. See [Delta](/integrations/graphql-api/objects/delta).
</ParamField>

<ParamField type="String!">
  The unique identifier of the conversation this message belongs to.
</ParamField>

<ParamField type="String">
  The unique identifier of the domain associated with this message.
</ParamField>

<ParamField type="Boolean!">
  Whether the message has been edited.
</ParamField>

<ParamField type="[String!]">
  Array of error messages if any errors occurred during message processing.
</ParamField>

<ParamField type="String">
  Optional message identifier for internal tracking.
</ParamField>

<ParamField type="ChatMessageSender!">
  The sender of the message. See [ChatMessageSender](/integrations/graphql-api/objects/chat-message-sender).
</ParamField>

<ParamField type="DateTime!">
  The date and time when the message was created.
</ParamField>

<ParamField type="DateTime!">
  The date and time when the message was last updated.
</ParamField>

<ParamField type="DateTime">
  The date and time when the message data was last refreshed. Null if never refreshed.
</ParamField>

<ParamField type="String">
  The unique identifier of the user who sent the message.
</ParamField>

<ParamField type="DateTime">
  The date and time when message generation was cancelled. Null if not cancelled.
</ParamField>

## Related operations

<CardGroup>
  <Card title="Delta Schema" icon="layer-group" href="/integrations/graphql-api/objects/delta">
    Learn about message content structure
  </Card>

  <Card title="ChatMessageSender Enum" icon="user" href="/integrations/graphql-api/objects/chat-message-sender">
    Message sender types
  </Card>

  <Card title="Subscribe Conversation" icon="wifi" href="/integrations/graphql-api/subscriptions/subscribe-conversation">
    Listen for message updates
  </Card>
</CardGroup>


# ChatMessageDiff
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/chat-message-diff



This page describes the differences in streaming messages when working with real-time updates.

## ChatMessageDiff

<ParamField type="Delta!">
  The incremental content changes for the message. See [Delta](/integrations/graphql-api/objects/delta).
</ParamField>

<ParamField type="String!">
  The unique identifier of the conversation this diff belongs to.
</ParamField>

<ParamField type="String">
  Optional message identifier for internal tracking.
</ParamField>

<ParamField type="ChatMessageSender!">
  The sender of the message. See [ChatMessageSender](/integrations/graphql-api/objects/chat-message-sender).
</ParamField>

<ParamField type="DateTime!">
  The date and time when the diff was created.
</ParamField>

<ParamField type="DateTime!">
  The date and time when the diff was last updated.
</ParamField>

<ParamField type="DateTime">
  The date and time when the diff data was refreshed. Null if not refreshed.
</ParamField>

<ParamField type="DateTime">
  The date and time when message generation was cancelled. Null if not cancelled.
</ParamField>

<ParamField type="Boolean!">
  Indicates whether the message generation is still in progress on the server.
</ParamField>

<ParamField type="String">
  The unique identifier of the domain associated with this diff.
</ParamField>

<ParamField type="String">
  The unique identifier of the user associated with this diff.
</ParamField>

<ParamField type="[String!]">
  Array of error messages if any errors occurred during processing.
</ParamField>

<ParamField type="Int!">
  The index of the diff in the stream for idempotent reconnects.
</ParamField>

## Related operations

<CardGroup>
  <Card title="Delta Schema" icon="layer-group" href="/integrations/graphql-api/objects/delta">
    Learn about content diff structure
  </Card>

  <Card title="ChatMessageSender Enum" icon="user" href="/integrations/graphql-api/objects/chat-message-sender">
    Message sender types
  </Card>

  <Card title="Subscribe Conversation" icon="wifi" href="/integrations/graphql-api/subscriptions/subscribe-conversation">
    Receive real-time message diffs
  </Card>
</CardGroup>


# ChatMessageSender
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/chat-message-sender



This page describes the available message sender types and what each represents.

## ChatMessageSender

The sender of a chat message. Here are the values and their description:

| Value       | Description                      |
| ----------- | -------------------------------- |
| `USER`      | Message sent by a user           |
| `ASSISTANT` | Message sent by the AI assistant |
| `SYSTEM`    | System-generated message         |

## Related operations

<CardGroup>
  <Card title="ChatMessage Schema" icon="message" href="/integrations/graphql-api/objects/chat-message">
    Messages with sender information
  </Card>

  <Card title="ChatMessageDiff Schema" icon="pen-to-square" href="/integrations/graphql-api/objects/chat-message-diff">
    Message diffs with sender information
  </Card>
</CardGroup>


# ChatThinkingEffort
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/chat-thinking-effort



This page describes the `ChatThinkingEffort` parameter, which allows you to control the computational effort the AI applies when generating a response. Adjusting this level lets you balance response speed against the depth and quality of the analysis.

## ChatThinkingEffort

The level of thinking effort to apply during AI response generation. This parameter accepts the following values:

| **Value**          | **Description**                                 |
| ------------------ | ----------------------------------------------- |
| `UNKNOWN_THINKING` | Effort level not specified                      |
| `LOW`              | Minimal thinking effort for quick responses     |
| `MEDIUM`           | Moderate thinking effort for balanced responses |
| `HIGH`             | Maximum thinking effort for complex analysis    |

## Related operation

<CardGroup>
  <Card title="Send User Message" icon="message" href="/integrations/graphql-api/mutations/chat/send-user-message">
    Configure thinking effort for messages
  </Card>
</CardGroup>


# CodegenConfig
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/codegen-config



This page describes the CodegenConfig object that represents the schema for domain code generation configuration.

## CodegenConfig

<ParamField type="ChatThinkingEffort!">
  Level of thinking effort for AI code generation. See [ChatThinkingEffort](/integrations/graphql-api/objects/chat-thinking-effort).
</ParamField>

<ParamField type="Boolean!">
  Whether to include today's date as a reference in generated queries.
</ParamField>

## Related operations

<CardGroup>
  <Card title="DomainModel Object" icon="folder" href="/integrations/graphql-api/objects/domain-model">
    Parent domain structure
  </Card>

  <Card title="ChatThinkingEffort Enum" icon="list" href="/integrations/graphql-api/objects/chat-thinking-effort">
    AI thinking effort levels
  </Card>
</CardGroup>


# Connection
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/connection



This page describes the schema used for data source connections, including all fields, types, and enums.

## Connection

<ParamField type="ID!">
  Unique identifier for the connection.
</ParamField>

<ParamField type="ConnectionDetails!">
  Configuration and metadata for the connection. See [ConnectionDetails](#connectiondetails).
</ParamField>

<ParamField type="JobHistory!">
  Job execution history for connection operations like metadata refresh. See [JobStatus](/integrations/graphql-api/objects/job-status).
</ParamField>

<ParamField type="DateTime!">
  Timestamp when the connection was created.
</ParamField>

## ConnectionDetails

<ParamField type="String!">
  Human-readable name for the connection.
</ParamField>

<ParamField type="String!">
  Description of the connection and its purpose.
</ParamField>

<ParamField type="DataSourceType!">
  The category of data source. See [DataSourceType](#datasourcetype).
</ParamField>

<ParamField type="ConnectionType!">
  The specific type of data source connection. See [ConnectionType](#connectiontype).
</ParamField>

<ParamField type="String!">
  The SQL dialect used by this connection.
</ParamField>

## Enums

### DataSourceType

The category of data source. It accepts the following values:

| Data Source Type               | Description                                           |
| ------------------------------ | ----------------------------------------------------- |
| `DATA_SOURCE_TYPE_UNSPECIFIED` | Type not specified                                    |
| `WAREHOUSE`                    | Data warehouse (Snowflake, BigQuery, Redshift, etc.)  |
| `BI_TOOL`                      | Business intelligence tool (Tableau, etc.)            |
| `FILE`                         | File-based data source (S3, Azure Blob Storage, etc.) |
| `DATA_SOURCE_MCP_SERVER`       | MCP server data source                                |

### ConnectionType

The specific type of data source connection. It accepts the following values:

| Connection Type               | Description                            |
| :---------------------------- | :------------------------------------- |
| `CONNECTION_TYPE_UNSPECIFIED` | Type not specified                     |
| `REDSHIFT`                    | Amazon Redshift data warehouse         |
| `SNOWFLAKE`                   | Snowflake data warehouse               |
| `TABLEAU`                     | Tableau business intelligence platform |
| `BIGQUERY`                    | Google BigQuery data warehouse         |
| `POSTGRES`                    | PostgreSQL database                    |
| `SQL_SERVER`                  | Microsoft SQL Server database          |
| `DATABRICKS`                  | Databricks analytics platform          |
| `MYSQL`                       | MySQL database                         |
| `CLICKHOUSE`                  | ClickHouse database                    |
| `ATHENA`                      | Amazon Athena query service            |
| `S3`                          | Amazon S3 file storage                 |
| `MCP_SERVER`                  | MCP server connection                  |
| `AZURE_SYNAPSE`               | Azure Synapse Analytics                |
| `AZURE_BLOB_STORAGE`          | Azure Blob Storage                     |
| `TRINO`                       | Trino distributed SQL query engine     |
| `AZURE_SYNAPSE_SERVERLESS`    | Azure Synapse Analytics Serverless     |
| `SHAREPOINT`                  | Microsoft SharePoint                   |
| `SPANNER`                     | Google Cloud Spanner                   |
| `TERADATA`                    | Teradata database                      |
| `DUCKDB`                      | DuckDB embedded database               |

## Related operations

<CardGroup>
  <Card title="Connection Queries" icon="magnifying-glass" href="/integrations/graphql-api/queries/connection/connection">
    Query connection information and status
  </Card>

  <Card title="JobStatus Schema" icon="clock" href="/integrations/graphql-api/objects/job-status">
    Learn about job execution status tracking
  </Card>

  <Card title="Refresh Connection" icon="arrows-rotate" href="/integrations/graphql-api/mutations/connection/refresh-connection">
    Trigger connection metadata refresh
  </Card>

  <Card title="Domain Objects" icon="folder" href="/integrations/graphql-api/objects/domain-model">
    Understand domain and table management
  </Card>
</CardGroup>


# ConversationUpdateOneOf
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/conversation-update-one-of



This page outlines the union type for real-time conversation updates and the object types it can include.

## ConversationUpdateOneOf

<ParamField type="ChatMessage">
  A complete message sent by the assistant. See [ChatMessage](/integrations/graphql-api/objects/chat-message).
</ParamField>

<ParamField type="ChatMessageDiff">
  A streaming diff update for an assistant's response in progress. See [ChatMessageDiff](/integrations/graphql-api/objects/chat-message-diff).
</ParamField>

<ParamField type="Boolean">
  Indicates whether the assistant's response was cancelled.
</ParamField>

## Related operations

<CardGroup>
  <Card title="Subscribe Conversation" icon="wifi" href="/integrations/graphql-api/subscriptions/subscribe-conversation">
    Subscribe to conversation updates
  </Card>

  <Card title="ChatMessage Schema" icon="message" href="/integrations/graphql-api/objects/chat-message">
    Learn about the complete message structure
  </Card>

  <Card title="ChatMessageDiff Schema" icon="pen-to-square" href="/integrations/graphql-api/objects/chat-message-diff">
    Understand streaming message updates
  </Card>
</CardGroup>


# Dashboard
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/dashboard



This page describes the Dashboard object that represents a collection of widgets and visualizations.

## Dashboard

<ParamField type="ID!">
  Unique identifier for the dashboard.
</ParamField>

<ParamField type="String!">
  Display name of the dashboard.
</ParamField>

<ParamField type="String">
  Optional description explaining the dashboard's purpose and contents.
</ParamField>

<ParamField type="User">
  User who created the dashboard. Null for system-generated dashboards.
</ParamField>

<ParamField type="ZSheet">
  Deprecated: Use `domains` field instead. Primary domain associated with the dashboard.
</ParamField>

<ParamField type="[ZSheet!]!">
  List of domains associated with this dashboard.
</ParamField>

<ParamField type="[DashboardWidget!]!">
  Array of widgets contained in this dashboard. See [DashboardWidget](/integrations/graphql-api/objects/dashboard-widget).
</ParamField>

<ParamField type="[DashboardFilterDefinition!]!">
  Global filter definitions applied to the dashboard. See [DashboardFilterDefinition](/integrations/graphql-api/objects/dashboard-filter-definition).
</ParamField>

<ParamField type="DateTime!">
  Timestamp when the dashboard was created.
</ParamField>

<ParamField type="DashboardScope!">
  Current user's access level to this dashboard. See [DashboardScope](/integrations/graphql-api/objects/dashboard-scope).
</ParamField>

<ParamField type="String">
  Version identifier for dashboard snapshots. Null if dashboard hasn't been modified.
</ParamField>

<ParamField type="[RoleAssignment!]!">
  List of user and group role assignments for this dashboard.
</ParamField>

## Related operations

<CardGroup>
  <Card title="Dashboard Query" icon="magnifying-glass" href="/integrations/graphql-api/queries/dashboard/dashboard">
    Retrieve dashboard by ID
  </Card>

  <Card title="Dashboards Query" icon="list" href="/integrations/graphql-api/queries/dashboard/dashboards">
    Retrieve multiple dashboards
  </Card>

  <Card title="DashboardWidget Object" icon="chart-bar" href="/integrations/graphql-api/objects/dashboard-widget">
    Widget structure and properties
  </Card>

  <Card title="DashboardScope Object" icon="shield" href="/integrations/graphql-api/objects/dashboard-scope">
    Access level definitions
  </Card>
</CardGroup>


# Dashboard Filter Definition
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/dashboard-filter-definition



This page describes the DashboardFilterDefinition object that defines global filters for dashboards.

## DashboardFilterDefinition

<ParamField type="ID!">
  Unique identifier for the filter definition.
</ParamField>

<ParamField type="ParsedFilter!">
  The parsed filter configuration.
</ParamField>

<ParamField type="[FilterAppliedState!]!">
  Array of widget-specific filter application states. See [FilterAppliedState](#filterappliedstate).
</ParamField>

## FilterAppliedState

<ParamField type="ID!">
  ID of the widget this filter state applies to.
</ParamField>

<ParamField type="ID!">
  ID of the filter as it exists on the specific widget.
</ParamField>

## Related operations

<CardGroup>
  <Card title="Dashboard Object" icon="folder" href="/integrations/graphql-api/objects/dashboard">
    Dashboard containing filter definitions
  </Card>

  <Card title="Update Dashboard Filters" icon="filter" href="/integrations/graphql-api/mutations/dashboard/update-dashboard-filters">
    Apply filter changes to dashboard
  </Card>
</CardGroup>


# Dashboard Input
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/dashboard-input



This page describes the DashboardInput object used for creating and updating dashboards.

## DashboardInput

<ParamField type="String">
  Optional dashboard ID for update operations. Omit for creation.
</ParamField>

<ParamField type="String!">
  Display name for the dashboard.
</ParamField>

<ParamField type="String">
  Optional description of the dashboard's purpose and contents.
</ParamField>

<ParamField type="String">
  Optional domain ID to associate with the dashboard.
</ParamField>

## Related operations

<CardGroup>
  <Card title="Create Dashboard" icon="plus" href="/integrations/graphql-api/mutations/dashboard/create-dashboard">
    Mutation using DashboardInput
  </Card>

  <Card title="Update Dashboard" icon="pen-to-square" href="/integrations/graphql-api/mutations/dashboard/update-dashboard">
    Update mutation using DashboardInput
  </Card>

  <Card title="Dashboard Object" icon="folder" href="/integrations/graphql-api/objects/dashboard">
    Resulting dashboard structure
  </Card>
</CardGroup>


# Dashboard Scope
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/dashboard-scope



This page describes the DashboardScope enum that defines access levels for dashboard operations.

## DashboardScope

The access level for dashboard operations. The possible values are:

| Value       | Description                          |
| ----------- | ------------------------------------ |
| `NO_ACCESS` | User has no access to the dashboard  |
| `VIEWER`    | User can view the dashboard          |
| `EDITOR`    | User can view and edit the dashboard |

## Related operations

<CardGroup>
  <Card title="Dashboard Object" icon="folder" href="/integrations/graphql-api/objects/dashboard">
    Dashboard with access level information
  </Card>

  <Card title="Dashboard Query" icon="magnifying-glass" href="/integrations/graphql-api/queries/dashboard/dashboard">
    Query requiring scope parameter
  </Card>
</CardGroup>


# DashboardSummaryDiff
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/dashboard-summary-diff



This page describes the differences in streaming summary when working with real-time updates.

## DashboardSummaryDiff

<ParamField type="String!">
  The incremental content changes for the summary.
</ParamField>

## Related operation

<CardGroup>
  <Card title="Dashboard Summary" icon="magnifying-glass" href="/integrations/graphql-api/subscriptions/dashboard-summary">
    Subscription requiring dashboard summary diff
  </Card>
</CardGroup>


# Dashboard Summary Type
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/dashboard-summary-type



This page describes the DashboardSummaryType enum that defines types of dashboard summaries.

## DashboardScope

The types of dashboard summaries. The possible values are:

| Value            | Description             |
| ---------------- | ----------------------- |
| `SIMPLE_SUMMARY` | Summarise the dashboard |

## Related operation

<CardGroup>
  <Card title="Dashboard Summary" icon="magnifying-glass" href="/integrations/graphql-api/subscriptions/dashboard-summary">
    Subscription requiring dashboard summary type
  </Card>
</CardGroup>


# Dashboard Widget
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/dashboard-widget



This page describes the DashboardWidget object that represents individual visualizations and content blocks within a dashboard.

## DashboardWidget

<ParamField type="ID!">
  Unique identifier for the widget.
</ParamField>

<ParamField type="ZSheet">
  Domain associated with this widget. May be null if the domain was deleted after widget creation.
</ParamField>

<ParamField type="String!">
  Display title for the widget.
</ParamField>

<ParamField type="String!">
  Natural language query that generated this widget's content.
</ParamField>

<ParamField type="Visualization">
  Chart or table visualization data. Null if there was an error generating the visualization. See [Visualization](/integrations/graphql-api/objects/visualization).
</ParamField>

<ParamField type="VisualizationType">
  Type of visualization (chart, table, etc.). See [VisualizationType](/integrations/graphql-api/objects/visualization-type).
</ParamField>

<ParamField type="WidgetLayout!">
  Positioning and sizing information for the widget. See [WidgetLayout](/integrations/graphql-api/objects/widget-layout).
</ParamField>

<ParamField type="DateTime!">
  Timestamp when the widget data was last refreshed.
</ParamField>

<ParamField type="String">
  ID of the conversation that generated this widget. Null if not sourced from a conversation.
</ParamField>

<ParamField type="String">
  ID of the message that generated this widget. Null if not sourced from a conversation.
</ParamField>

<ParamField type="Boolean!">
  Whether the current user can ask follow-up questions about this widget.
</ParamField>

<ParamField type="Boolean!">
  Whether the current user can view the original conversation message that generated this widget.
</ParamField>

<ParamField type="WidgetType!">
  Type of widget content. See [WidgetType](#widgettype).
</ParamField>

<ParamField type="String">
  Markdown content for text/markdown widgets.
</ParamField>

## WidgetType

The type of content displayed in the widget. The possible values are:

| Value                       | Description                   |
| --------------------------- | ----------------------------- |
| `WIDGET_TYPE_UNKNOWN`       | Unknown widget type           |
| `WIDGET_TYPE_VISUALIZATION` | Chart or table visualization  |
| `WIDGET_TYPE_MARKDOWN`      | Rich text content             |
| `WIDGET_TYPE_SUMMARY`       | Summary or aggregated content |

## Related operations

<CardGroup>
  <Card title="Dashboard Object" icon="folder" href="/integrations/graphql-api/objects/dashboard">
    Parent dashboard structure
  </Card>

  <Card title="WidgetLayout Object" icon="table-layout" href="/integrations/graphql-api/objects/widget-layout">
    Widget positioning and sizing
  </Card>

  <Card title="Visualization Object" icon="chart-bar" href="/integrations/graphql-api/objects/visualization">
    Chart and table data structure
  </Card>

  <Card title="Update Dashboard Widgets" icon="pen-to-square" href="/integrations/graphql-api/mutations/dashboard/update-dashboard-widgets">
    Modify widget properties
  </Card>
</CardGroup>


# Dashboard Widget Input
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/dashboard-widget-input



This page describes the DashboardWidgetInput object used for creating and updating dashboard widgets.

## DashboardWidgetInput

<ParamField type="String">
  Optional widget ID for update operations. Omit for creation.
</ParamField>

<ParamField type="String">
  Optional domain ID associated with the widget.
</ParamField>

<ParamField type="String">
  Optional display title. If null, the natural language query will be used as title.
</ParamField>

<ParamField type="String">
  Natural language query for generating the widget content.
</ParamField>

<ParamField type="String">
  Optional ID of an existing visualization to use for the widget.
</ParamField>

<ParamField type="VisualizationType">
  Optional visualization type. If null, will be determined from the natural language query. See [VisualizationType](/integrations/graphql-api/objects/visualization-type).
</ParamField>

<ParamField type="WidgetLayoutInput">
  Positioning and sizing information for the widget. See [WidgetLayoutInput](/integrations/graphql-api/objects/widget-layout-input).
</ParamField>

<ParamField type="String">
  Optional ID of the conversation that generated this widget.
</ParamField>

<ParamField type="String">
  Optional ID of the message that generated this widget.
</ParamField>

<ParamField type="DateTime">
  Optional timestamp for when data was last refreshed.
</ParamField>

<ParamField type="UpdateChatMessageBodyOneOf">
  Optional message body for chat-based widget updates.
</ParamField>

<ParamField type="WidgetType">
  Type of widget content. See [WidgetType](/integrations/graphql-api/objects/dashboard-widget#widgettype).
</ParamField>

<ParamField type="String">
  Markdown content for text/markdown widgets.
</ParamField>

## Related operations

<CardGroup>
  <Card title="DashboardWidget Object" icon="chart-bar" href="/integrations/graphql-api/objects/dashboard-widget">
    Resulting widget structure
  </Card>

  <Card title="Create Dashboard" icon="plus" href="/integrations/graphql-api/mutations/dashboard/create-dashboard">
    Mutation using DashboardWidgetInput
  </Card>

  <Card title="Update Dashboard Widgets" icon="pen-to-square" href="/integrations/graphql-api/mutations/dashboard/update-dashboard-widgets">
    Update mutation using DashboardWidgetInput
  </Card>
</CardGroup>


# Dashboards Response
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/dashboards-response



This page describes the DashboardsResponse object returned by dashboard listing queries.

## DashboardsResponse

<ParamField type="[Dashboard!]!">
  Array of dashboard objects matching the query criteria. See [Dashboard](/integrations/graphql-api/objects/dashboard).
</ParamField>

<ParamField type="PageInfo!">
  Pagination information for the result set.
</ParamField>

## Related operations

<CardGroup>
  <Card title="Dashboards Query" icon="list" href="/integrations/graphql-api/queries/dashboard/dashboards">
    Query that returns this response
  </Card>

  <Card title="Dashboard Object" icon="folder" href="/integrations/graphql-api/objects/dashboard">
    Individual dashboard structure
  </Card>
</CardGroup>


# DataLabelMode
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/data-label-mode



This page describes the DataLabelMode enum that controls how data labels appear on visualizations.

## DataLabelMode

The mode for displaying data labels on visualizations. The possible values are:

| Value                       | Description                                    |
| --------------------------- | ---------------------------------------------- |
| `DATA_LABEL_MODE_AUTOMATIC` | Labels shown automatically based on chart type |
| `DATA_LABEL_MODE_ALWAYS`    | Labels always displayed                        |
| `DATA_LABEL_MODE_NONE`      | Labels never displayed                         |

## Related operations

<CardGroup>
  <Card title="VizConfig Object" icon="gear" href="/integrations/graphql-api/objects/viz-config">
    Visualization configuration
  </Card>

  <Card title="DomainModel Object" icon="folder" href="/integrations/graphql-api/objects/domain-model">
    Parent domain structure
  </Card>
</CardGroup>


# DatabaseModel
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/database-model



This page describes the DatabaseModel object that represents the schema for database objects within a domain.

## DatabaseModel

<ParamField type="ID!">
  Unique identifier for the database.
</ParamField>

<ParamField type="DatabaseType">
  The type of database. See [DatabaseType](/integrations/graphql-api/objects/database-type).
</ParamField>

<ParamField type="Int">
  Version number of the database for change tracking.
</ParamField>

<ParamField type="String!">
  Name of the database.
</ParamField>

<ParamField type="String">
  Optional display name for the database.
</ParamField>

<ParamField type="ID!">
  Identifier of the domain this database belongs to.
</ParamField>

<ParamField type="Connection">
  Connection details for accessing this database. See [Connection](/integrations/graphql-api/objects/connection).
</ParamField>

<ParamField type="[TableModel!]">
  List of tables in this database.
</ParamField>

<ParamField type="Boolean">
  Whether this database was created from user-uploaded CSV files.
</ParamField>

## Related operations

<CardGroup>
  <Card title="DomainModel Object" icon="folder" href="/integrations/graphql-api/objects/domain-model">
    Parent domain structure
  </Card>

  <Card title="Connection Object" icon="link" href="/integrations/graphql-api/objects/connection">
    Database connection details
  </Card>

  <Card title="DatabaseType Enum" icon="list" href="/integrations/graphql-api/objects/database-type">
    Database type definitions
  </Card>
</CardGroup>


# DatabaseType
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/database-type



This page describes the DatabaseType enum that defines the type of database connection.

## DatabaseType

The type of database connection. The possible values are:

| Value                       | Description               |
| --------------------------- | ------------------------- |
| `DATABASE_TYPE_UNSPECIFIED` | Type not specified        |
| `DATABASE_TYPE_WAREHOUSE`   | Data warehouse connection |
| `DATABASE_TYPE_FILESYSTEM`  | File-based data source    |

## Related operations

<CardGroup>
  <Card title="DatabaseModel Object" icon="database" href="/integrations/graphql-api/objects/database-model">
    Database object structure
  </Card>

  <Card title="DomainModel Object" icon="folder" href="/integrations/graphql-api/objects/domain-model">
    Parent domain structure
  </Card>
</CardGroup>


# Delta
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/delta



This page describes the input structure used for message content operations.

## Delta

<ParamField type="[Operation!]!">
  Array of operations that define the message content. See [Operation](/integrations/graphql-api/objects/operation).
</ParamField>

## Related operations

<CardGroup>
  <Card title="Operation Schema" icon="gear" href="/integrations/graphql-api/objects/operation">
    Learn about individual operations
  </Card>

  <Card title="DeltaInput Schema" icon="pen-to-square" href="/integrations/graphql-api/objects/delta-input">
    Input version for sending messages
  </Card>

  <Card title="ChatMessage Schema" icon="message" href="/integrations/graphql-api/objects/chat-message">
    Messages containing Delta content
  </Card>
</CardGroup>


# DeltaElement
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/delta-element



This page describes the content elements that can be inserted in operations.

## DeltaElement

<ParamField type="String">
  Plain text content to insert.
</ParamField>

<ParamField type="Visualization">
  Chart, table, or other data visualization. See [Visualization](/integrations/graphql-api/objects/visualization).
</ParamField>

<ParamField type="DataframeExpression">
  Data expression or formula reference.
</ParamField>

<ParamField type="Int">
  Reference to another message by ID.
</ParamField>

<ParamField type="Reference">
  Reference to external resources or entities.
</ParamField>

<ParamField type="VizReference">
  Reference to a visualization element.
</ParamField>

<ParamField type="TextArtifact">
  Rich text content with references and metadata. See [TextArtifact](/integrations/graphql-api/objects/text-artifact).
</ParamField>

<ParamField type="LLMToolCalls">
  AI function calls made by the assistant. See [LLMToolCalls](/integrations/graphql-api/objects/llm-tool-calls).
</ParamField>

<ParamField type="LLMToolCallResults">
  Results from AI function calls. See [LLMToolCallResults](/integrations/graphql-api/objects/llm-tool-call-results).
</ParamField>

<ParamField type="AIWorkstream">
  AI workflow information and status. See [AIWorkstream](/integrations/graphql-api/objects/ai-workstream).
</ParamField>

<ParamField type="Section">
  Content section with title and body. See [Section](/integrations/graphql-api/objects/section).
</ParamField>

## Related operations

<CardGroup>
  <Card title="Operation Schema" icon="bagel" href="/integrations/graphql-api/objects/operation">
    Operations containing DeltaElement
  </Card>

  <Card title="Visualization Schema" icon="chart-bar" href="/integrations/graphql-api/objects/visualization">
    Chart and table visualizations
  </Card>

  <Card title="TextArtifact Schema" icon="file-lines" href="/integrations/graphql-api/objects/text-artifact">
    Rich text content with references
  </Card>

  <Card title="LLMToolCalls Schema" icon="gear" href="/integrations/graphql-api/objects/llm-tool-calls">
    AI function calls
  </Card>
</CardGroup>


# DeltaInput
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/delta-input



## DeltaInput

<ParamField type="[OperationInput!]!">
  Array of operation inputs that define the message content.
</ParamField>

## Related operations

<CardGroup>
  <Card title="Send User Message" icon="message" href="/integrations/graphql-api/mutations/chat/send-user-message">
    Use DeltaInput to send messages
  </Card>

  <Card title="Delta Schema" icon="layer-group" href="/integrations/graphql-api/objects/delta">
    Output version of Delta
  </Card>
</CardGroup>


# DomainModel
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/domain-model



This page describes the schema for domain objects that organize related data sources.

## DomainModel

<ParamField type="ID!">
  Unique identifier for the domain.
</ParamField>

<ParamField type="Int!">
  Version number of the domain for change tracking.
</ParamField>

<ParamField type="String!">
  Human-readable name for the domain.
</ParamField>

<ParamField type="String">
  Optional description explaining the purpose and contents of the domain.
</ParamField>

<ParamField type="[DatabaseModel!]!">
  List of databases included in this domain. See [DatabaseModel](/integrations/graphql-api/objects/database-model).
</ParamField>

<ParamField type="[Dataset!]!">
  Datasets (file-based data sources) associated with this domain, including S3, Azure Blob Storage, SharePoint, and Wisdom-managed datasets.
</ParamField>

<ParamField type="[Knowledge!]!">
  Domain-specific knowledge entries. See [Knowledge](/integrations/graphql-api/objects/knowledge).
</ParamField>

<ParamField type="String">
  Custom system instructions for AI interactions within this domain.
</ParamField>

<ParamField type="Int">
  Fiscal year start month (1-12) for financial calculations.
</ParamField>

<ParamField type="String">
  Timezone used for date and time calculations in this domain.
</ParamField>

<ParamField type="VizConfig!">
  Visualization configuration settings. See [VizConfig](/integrations/graphql-api/objects/viz-config).
</ParamField>

<ParamField type="CodegenConfig!">
  Code generation configuration settings. See [CodegenConfig](/integrations/graphql-api/objects/codegen-config).
</ParamField>

<ParamField type="[TableJoin!]!">
  List of join relationships between tables in this domain.
</ParamField>

<ParamField type="DomainWebSearchConfig">
  Web search configuration for this domain. See [DomainWebSearchConfig](/integrations/graphql-api/objects/domain-web-search-config).
</ParamField>

<ParamField type="CanvasConfig!">
  Canvas configuration settings. See [CanvasConfig](/integrations/graphql-api/objects/canvas-config).
</ParamField>

<ParamField type="DomainRLSConfig">
  Row-level security configuration for this domain. See [DomainRLSConfig](/integrations/graphql-api/objects/domain-rls-config).
</ParamField>

<ParamField type="DateTime">
  ISO timestamp when the domain was last modified.
</ParamField>

<ParamField type="String">
  Full name of the user who created this domain.
</ParamField>

<ParamField type="Boolean!">
  Whether this domain was automatically generated by the system.
</ParamField>

## Related operations

<CardGroup>
  <Card title="Create Domain" icon="plus" href="/integrations/graphql-api/mutations/domain/create-domain">
    Create new domains for organizing data sources
  </Card>

  <Card title="Duplicate Domain" icon="copy" href="/integrations/graphql-api/mutations/domain/duplicate-domain">
    Duplicate an existing domain
  </Card>

  <Card title="DatabaseModel" icon="database" href="/integrations/graphql-api/objects/database-model">
    Database structure within a domain
  </Card>

  <Card title="Knowledge" icon="book" href="/integrations/graphql-api/objects/knowledge">
    Domain knowledge entries
  </Card>

  <Card title="VizConfig" icon="gear" href="/integrations/graphql-api/objects/viz-config">
    Visualization configuration
  </Card>

  <Card title="CodegenConfig" icon="code" href="/integrations/graphql-api/objects/codegen-config">
    Code generation configuration
  </Card>

  <Card title="Connection" icon="link" href="/integrations/graphql-api/objects/connection">
    Connection schema and properties
  </Card>
</CardGroup>


# DomainRLSConfig
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/domain-rls-config



This page describes the DomainRLSConfig object that represents the schema for domain row-level security configuration.

## DomainRLSConfig

<ParamField type="Boolean!">
  Whether row-level security is enforced for admin users.
</ParamField>

## Related operations

<CardGroup>
  <Card title="DomainModel Object" icon="folder" href="/integrations/graphql-api/objects/domain-model">
    Parent domain structure
  </Card>
</CardGroup>


# DomainWebSearchConfig
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/domain-web-search-config



This page describes the DomainWebSearchConfig object that represents the schema for domain web search configuration.

## DomainWebSearchConfig

<ParamField type="Boolean!">
  Whether web search is enabled for this domain.
</ParamField>

<ParamField type="[String!]!">
  List of web domains to include in search results.
</ParamField>

<ParamField type="[String!]!">
  List of web domains to exclude from search results.
</ParamField>

## Related operations

<CardGroup>
  <Card title="DomainModel Object" icon="folder" href="/integrations/graphql-api/objects/domain-model">
    Parent domain structure
  </Card>
</CardGroup>


# Filter Applied State
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/filter-applied-state



This page describes the FilterAppliedState object that tracks how filters are applied to individual widgets.

## FilterAppliedState

<ParamField type="ID!">
  Unique identifier of the widget this filter state applies to.
</ParamField>

<ParamField type="ID!">
  Identifier of the filter as it exists on the specific widget.
</ParamField>

## Related operations

<CardGroup>
  <Card title="DashboardFilterDefinition Object" icon="filter" href="/integrations/graphql-api/objects/dashboard-filter-definition">
    Parent filter definition
  </Card>

  <Card title="DashboardWidget Object" icon="chart-bar" href="/integrations/graphql-api/objects/dashboard-widget">
    Widget that filter applies to
  </Card>
</CardGroup>


# JobStatus
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/job-status



This page describes the schema for Job Status.

## JobStatus

<ParamField type="JobRun">
  Information about the most recent job execution attempt. See [JobRun](#jobrun).
</ParamField>

<ParamField type="JobRun">
  Information about the most recent successful job execution. See [JobRun](#jobrun).
</ParamField>

## JobRun

<ParamField type="String!">
  Unique identifier for this specific job execution.
</ParamField>

<ParamField type="String!">
  Identifier for the job definition that was executed.
</ParamField>

<ParamField type="String!">
  The type of job that was executed (e.g., `CRAWL_METADATA` for connection refresh operations).
</ParamField>

<ParamField type="String!">
  Identifier of the user who initiated the job execution.
</ParamField>

<ParamField type="JobRunStatus!">
  The current status of the job execution. See [JobRunStatus](#jobrunstatus).
</ParamField>

<ParamField type="String">
  ISO 8601 timestamp when the job execution started.
</ParamField>

<ParamField type="String">
  ISO 8601 timestamp when the job execution completed (successfully or with failure).
</ParamField>

<ParamField type="String">
  Human-readable summary of the job execution result.
</ParamField>

<ParamField type="String">
  Brief error message if the job failed, null if successful.
</ParamField>

<ParamField type="String!">
  ISO 8601 timestamp when the job execution record was created.
</ParamField>

## JobRunStatus

The status of a job execution. This parameter can have one of the following values:

| Status                   | Description                              |
| :----------------------- | :--------------------------------------- |
| `JOB_RUN_STATUS_UNKNOWN` | Status is unknown or not set             |
| `JOB_RUN_STATUS_QUEUED`  | Job is queued and waiting to be executed |
| `JOB_RUN_STATUS_RUNNING` | Job is currently executing               |
| `JOB_RUN_STATUS_SUCCESS` | Job completed successfully               |
| `JOB_RUN_STATUS_FAILED`  | Job failed with errors                   |
| `JOB_RUN_STATUS_SKIPPED` | Job was skipped                          |

## Related operations

<CardGroup>
  <Card title="Connection Queries" icon="magnifying-glass" href="/integrations/graphql-api/queries/connection/connection">
    Query connection status and metadata
  </Card>

  <Card title="Refresh Connection" icon="arrows-rotate" href="/integrations/graphql-api/mutations/connection/refresh-connection">
    Trigger connection metadata refresh
  </Card>
</CardGroup>


# JoinInput
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/join-input



This page describes the schema for join input objects used to define table relationships.

## JoinInput

Input type for specifying join relationships between tables when updating data sources in a domain.

<ParamField type="TableInput!">
  The left table in the join relationship. See [TableInput](/integrations/graphql-api/objects/table-input).
</ParamField>

<ParamField type="TableInput!">
  The right table in the join relationship. See [TableInput](/integrations/graphql-api/objects/table-input).
</ParamField>

<ParamField type="RelationshipType!">
  The type of relationship between the tables. See [RelationshipType](#relationshiptype).
</ParamField>

<ParamField type="[JoinConditionInput!]!">
  List of join conditions that define how the tables are connected. See [JoinConditionInput](#joinconditioninput).
</ParamField>

## JoinConditionInput

Defines a single join condition between two table columns.

<ParamField type="String!">
  The name of the column in the left table to join on.
</ParamField>

<ParamField type="String!">
  The name of the column in the right table to join on.
</ParamField>

## RelationshipType

The `RelationshipType` enum defines the cardinality between joined tables and can be set to one of the following values:

| Relationship Type           | Description                                                                       |
| :-------------------------- | :-------------------------------------------------------------------------------- |
| `RELATIONSHIP_TYPE_UNKNOWN` | Relationship type is not specified or unclear.                                    |
| `ONE_TO_ONE`                | Each record in the left table matches exactly one record in the right table.      |
| `ONE_TO_MANY`               | Each record in the left table can match multiple records in the right table.      |
| `MANY_TO_ONE`               | Multiple records in the left table can match one record in the right table.       |
| `MANY_TO_MANY`              | Multiple records in the left table can match multiple records in the right table. |

## Related operations

<CardGroup>
  <Card title="Update Data Sources" icon="arrows-rotate" href="/integrations/graphql-api/mutations/domain/update-data-sources">
    Use JoinInput to define table relationships
  </Card>

  <Card title="TableInput Schema" icon="table" href="/integrations/graphql-api/objects/table-input">
    Configure tables that participate in joins
  </Card>

  <Card title="DomainModel Schema" icon="folder" href="/integrations/graphql-api/objects/domain-model">
    Understand how joins fit within domain structure
  </Card>

  <Card title="Create Domain" icon="plus" href="/integrations/graphql-api/mutations/domain/create-domain">
    Start with domain creation before adding joins
  </Card>
</CardGroup>


# Knowledge
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/knowledge



This page describes the Knowledge object that represents the schema for domain knowledge entries.

## Knowledge

<ParamField type="String">
  Name or label for this knowledge entry.
</ParamField>

<ParamField type="String!">
  The knowledge content or description.
</ParamField>

<ParamField type="DateTime">
  Timestamp when this knowledge entry was last updated.
</ParamField>

<ParamField type="User">
  The user who last updated this knowledge entry. See [User](/integrations/graphql-api/objects/user).
</ParamField>

## Related operations

<CardGroup>
  <Card title="DomainModel Object" icon="folder" href="/integrations/graphql-api/objects/domain-model">
    Parent domain structure
  </Card>

  <Card title="User Object" icon="user" href="/integrations/graphql-api/objects/user">
    User who updated this entry
  </Card>
</CardGroup>


# LLMToolCallResults
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/llm-tool-call-results



This page describes the results returned from AI function calls, grouped together and including details for each individual function invocation.

## LLMToolCallResults

<ParamField type="String!">
  Unique identifier for the result group.
</ParamField>

<ParamField type="[LLMFunctionCallResult!]!">
  Array of individual function call results.
</ParamField>

## LLMFunctionCallResult

<ParamField type="String!">
  Unique identifier for the function call result.
</ParamField>

<ParamField type="String!">
  Name of the function that was called.
</ParamField>

<ParamField type="String!">
  The result returned by the function call.
</ParamField>

<ParamField type="String!">
  Identifier linking this result to its original call.
</ParamField>

## Related operations

<CardGroup>
  <Card title="LLMToolCalls Schema" icon="gear" href="/integrations/graphql-api/objects/llm-tool-calls">
    Original tool calls
  </Card>

  <Card title="DeltaElement Schema" icon="cube" href="/integrations/graphql-api/objects/delta-element">
    Container for tool call results
  </Card>
</CardGroup>


# LLMToolCalls
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/llm-tool-calls



This page describes the AI function calls made by the assistant, including details for each individual call and their associated arguments.

## LLMToolCalls

<ParamField type="String!">
  Unique identifier for the tool call group.
</ParamField>

<ParamField type="[LLMFunctionCall!]!">
  Array of individual function calls made by the AI.
</ParamField>

## LLMFunctionCall

<ParamField type="String!">
  Unique identifier for the function call.
</ParamField>

<ParamField type="String!">
  Name of the function being called.
</ParamField>

<ParamField type="JSON">
  JSON object containing the function arguments.
</ParamField>

<ParamField type="String!">
  Identifier linking this call to its result.
</ParamField>

## Related operations

<CardGroup>
  <Card title="LLMToolCallResults Schema" icon="check" href="/integrations/graphql-api/objects/llm-tool-call-results">
    Results from tool calls
  </Card>

  <Card title="DeltaElement Schema" icon="cube" href="/integrations/graphql-api/objects/delta-element">
    Container for tool calls
  </Card>
</CardGroup>


# Operation
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/operation



This page describes individual operations within Delta content.

## Operation

<ParamField type="DeltaElement">
  Content to insert at the current position. See [DeltaElement](/integrations/graphql-api/objects/delta-element).
</ParamField>

<ParamField type="Int">
  Number of characters to delete from the current position.
</ParamField>

<ParamField type="Int">
  Number of characters to retain from the current position.
</ParamField>

<ParamField type="Attributes">
  Formatting and metadata attributes for the operation. See [Attributes](/integrations/graphql-api/objects/attributes).
</ParamField>

## Related operations

<CardGroup>
  <Card title="DeltaElement Schema" icon="cube" href="/integrations/graphql-api/objects/delta-element">
    Content elements for insert operations
  </Card>

  <Card title="Attributes Schema" icon="tag" href="/integrations/graphql-api/objects/attributes">
    Operation formatting and metadata
  </Card>

  <Card title="Delta Schema" icon="layer-group" href="/integrations/graphql-api/objects/delta">
    Container for operations
  </Card>
</CardGroup>


# ResponseStatus
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/response-status



`ResponseStatus` is returned by mutations to indicate whether the operation succeeded. It is a distinct type from the `UserStatus` enum — mutation responses use this object, not the enum.

## Fields

<ParamField type="StatusCode!">
  A code indicating the result of the operation. `OK` means the operation succeeded; any other value indicates failure.
</ParamField>

<ParamField type="String!">
  A human-readable message describing the result. On failure, this field contains the error details.
</ParamField>

## StatusCode enum

```graphql theme={null}
enum StatusCode {
  NONE
  OK
  ERROR
  NOT_FOUND
}
```

## Example values

```json Success theme={null}
{
  "status": {
    "code": "OK",
    "message": "Operation completed successfully"
  }
}
```

```json Failure theme={null}
{
  "status": {
    "code": "ERROR",
    "message": "User with email alice@yourcompany.com already exists"
  }
}
```

```json Not found theme={null}
{
  "status": {
    "code": "NOT_FOUND",
    "message": "User not found"
  }
}
```

<Note>
  GraphQL returns HTTP 200 even when `status.code` is not `"OK"`. Always check the `code` field in the response body to determine success or failure. See [Error handling](/integrations/graphql-api/GraphQL-API#error-handling).
</Note>

<Note>
  When querying mutations, you must explicitly request `{ status { code message } }` — requesting just `{ status }` returns nothing.
</Note>

## Operations that return ResponseStatus

<CardGroup>
  <Card title="Create users" icon="user-plus" href="/integrations/graphql-api/mutations/user/create-users">
    Returns ResponseStatus
  </Card>

  <Card title="Set user attributes" icon="tag" href="/integrations/graphql-api/mutations/user/set-user-attributes">
    Returns ResponseStatus
  </Card>

  <Card title="Delete users from workspace" icon="user-minus" href="/integrations/graphql-api/mutations/user/delete-users-from-workspace">
    Returns ResponseStatus
  </Card>
</CardGroup>


# Scope Role Assignment Input
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/scope-role-assignment-input



This page describes the `ScopeRoleAssignmentInput` object used for managing user access to shared resources like Dashboards.

## ScopeRoleAssignmentInput

<ParamField type="ID!">
  The identifier of the role to assign. For Dashboards, use:

  * `00000000-0000-0000-0000-000000000008` for viewer access (read-only)
  * `00000000-0000-0000-0000-000000000009` for editor access (read and write)
</ParamField>

<ParamField type="String!">
  The unique identifier of the user who will receive the specified role and access to the shared resource.
</ParamField>

## Related operations

<CardGroup>
  <Card title="Add Scope Role Assignments for Sharing" icon="user-plus" href="/integrations/graphql-api/mutations/dashboard/add-scope-role-assignments-for-sharing">
    Grant access using ScopeRoleAssignmentInput
  </Card>

  <Card title="Remove Scope Role Assignments for Sharing" icon="user-minus" href="/integrations/graphql-api/mutations/dashboard/remove-scope-role-assignments-for-sharing">
    Remove access using ScopeRoleAssignmentInput
  </Card>
</CardGroup>


# Section
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/section



This page describes the content section structure, including title and body.

## Section

<ParamField type="String!">
  The title or heading of the section.
</ParamField>

<ParamField type="String!">
  The main content body of the section.
</ParamField>

## Related operations

<CardGroup>
  <Card title="DeltaElement Schema" icon="cube" href="/integrations/graphql-api/objects/delta-element">
    Container for sections
  </Card>
</CardGroup>


# SubscriptionAuthInput
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/subscription-auth-input



This page describes the authentication input used for GraphQL subscriptions.

## SubscriptionAuthInput

<ParamField type="String!">
  JWT authentication token for subscription access.
</ParamField>

## Related operation

<CardGroup>
  <Card title="Subscribe Conversation" icon="wifi" href="/integrations/graphql-api/subscriptions/subscribe-conversation">
    Use authentication with subscriptions
  </Card>
</CardGroup>


# TableInput
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/table-input



This page describes the schema for table input objects used in data source operations.

## TableInput

<ParamField type="String!">
  The unique identifier of the connection that provides access to this table.
</ParamField>

<ParamField type="String!">
  The name of the database containing this table.

  Use the following as `database_name` for:

  * **BigQuery**: Use the Project ID (e.g., `"my-project-123"`)
  * **Databricks**: Use the Catalog name (e.g., `"main"`)
</ParamField>

<ParamField type="String">
  Schema name within the database. Optional for data sources which don't have the notion of a schema.

  Use the following as `schema_name` for:

  * **BigQuery**: Use the Dataset name (e.g., `"sales_data"`)
  * **Databricks**: Use the Schema name (e.g., `"default"`)
  * **MySQL, ClickHouse**: Do not pass or leave empty (`""`)
</ParamField>

<ParamField type="String!">
  The name of the table within the specified database and schema.
</ParamField>

## Related operations

<CardGroup>
  <Card title="Update Data Sources" icon="arrows-rotate" href="/integrations/graphql-api/mutations/domain/update-data-sources">
    Use TableInput to update domain data sources
  </Card>

  <Card title="JoinInput Schema" icon="link" href="/integrations/graphql-api/objects/join-input">
    Configure relationships between tables
  </Card>

  <Card title="Connection Objects" icon="database" href="/integrations/graphql-api/objects/connection">
    Learn about connection configuration
  </Card>

  <Card title="DomainModel Schema" icon="folder" href="/integrations/graphql-api/objects/domain-model">
    Understand domain structure and table organization
  </Card>
</CardGroup>


# TextArtifact
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/text-artifact



This page describes rich text content that includes references and metadata.

## TextArtifact

<ParamField type="ID!">
  Unique identifier for the text artifact.
</ParamField>

<ParamField type="String!">
  The main text content of the artifact.
</ParamField>

<ParamField type="[Reference!]!">
  Array of references to external resources or entities.
</ParamField>

<ParamField type="Int!">
  Number of search hits or matches found.
</ParamField>

<ParamField type="[String!]!">
  Array of filter strings applied to the content.
</ParamField>

<ParamField type="ID">
  Optional reference to a related ZSheet.
</ParamField>

<ParamField type="ID">
  Optional reference to a related dataset.
</ParamField>

## Related operation

<CardGroup>
  <Card title="DeltaElement Schema" icon="cube" href="/integrations/graphql-api/objects/delta-element">
    Container for text artifacts
  </Card>
</CardGroup>


# ToolSelection
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/tool-selection



This page describes the tool selection configuration used for message processing.

## ToolSelection

<ParamField type="[ChatToolName!]">
  Array of specific tools to enable for message processing.

  Supported values:

  * `TABULAR_DATA`: Enables querying databases.
  * `TEXTUAL_DATA`: Enables querying unstructured documents.

  ```
    "toolSelection": {
      "optInToolNames": [
          "TABULAR_DATA",
          "TEXTUAL_DATA"
        ]
      }
  ```
</ParamField>

## Related operation

<CardGroup>
  <Card title="Send User Message" icon="message" href="/integrations/graphql-api/mutations/chat/send-user-message">
    Use ToolSelection with messages
  </Card>
</CardGroup>


# User
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/user



This page describes the User object that represents a user account in WisdomAI.

## User

<ParamField type="ID!">
  A unique identifier for the user.
</ParamField>

<ParamField type="String!">
  The user's email address.
</ParamField>

<ParamField type="String!">
  The user's display name.
</ParamField>

<ParamField type="String!">
  URL to the user's profile picture.
</ParamField>

<ParamField type="String!">
  Timestamp when the user account was created.
</ParamField>

<ParamField type="String">
  Timestamp of the user's last active session. Null if the user has never logged in.
</ParamField>

<ParamField type="[RoleAssignment!]!">
  List of role assignments granted to this user.
</ParamField>

<ParamField type="[UserAttribute!]!">
  User attributes from the authentication token.
</ParamField>

<ParamField type="Boolean!">
  Whether this user account is managed via SCIM provisioning.
</ParamField>

## Related operations

<CardGroup>
  <Card title="Current User Query" icon="magnifying-glass" href="/integrations/graphql-api/queries/user/current-user">
    Query the current authenticated user
  </Card>
</CardGroup>


# Visualization
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/visualization



This page describes chart, table, and data visualization objects.

## Visualization

<ParamField type="String!">
  Unique identifier for the visualization.
</ParamField>

<ParamField type="VisualizationType!">
  The type of visualization. See [VisualizationType](/integrations/graphql-api/objects/visualization-type).
</ParamField>

<ParamField type="String!">
  Display title for the visualization.
</ParamField>

<ParamField type="VisualizationType!">
  Original type before user modifications.
</ParamField>

<ParamField type="[[Cell!]!]!">
  Two-dimensional array of data cells representing the visualization data.
</ParamField>

<ParamField type="[Subtotal!]">
  Subtotal aggregations for drilled-down data.
</ParamField>

<ParamField type="Boolean!">
  Whether additional data is available beyond the current page.
</ParamField>

<ParamField type="Pagination!">
  Pagination information for the data.
</ParamField>

<ParamField type="Int">
  Total number of rows in the complete dataset.
</ParamField>

<ParamField type="[DataframeColumn!]!">
  Column definitions in display order.
</ParamField>

<ParamField type="[DisplayFormat!]!">
  Display formatting for each column.
</ParamField>

<ParamField type="[String!]!">
  Preferred column order for table views.
</ParamField>

<ParamField type="[String!]!">
  Dimension columns for grouping data.
</ParamField>

<ParamField type="[String!]!">
  Unique dimension values.
</ParamField>

<ParamField type="[String!]!">
  Measure columns for numeric analysis.
</ParamField>

<ParamField type="[MeasureGroup!]!">
  Grouped measures with formatting information.
</ParamField>

<ParamField type="[MapDimensionPair!]!">
  Geographic dimension pairs for map visualizations.
</ParamField>

<ParamField type="String">
  Column used for color coding in map visualizations.
</ParamField>

<ParamField type="[String!]!">
  Columns displayed in map tooltips.
</ParamField>

<ParamField type="[FilterOperation!]!">
  Applied filter operations.
</ParamField>

<ParamField type="[ParsedFilter!]!">
  Human-readable filter representations.
</ParamField>

<ParamField type="[FilterOperation!]!">
  Raw filter operations not yet processed.
</ParamField>

<ParamField type="SortOperation">
  Applied sorting configuration.
</ParamField>

<ParamField type="[UpdateVisualization!]">
  Available update operations for the visualization.
</ParamField>

<ParamField type="[DataframeColumn!]">
  Sequence of drill-down operations applied.
</ParamField>

<ParamField type="Code">
  Generated SQL or code for the visualization.
</ParamField>

<ParamField type="CodegenConfidenceInfo">
  Confidence level information for generated code.
</ParamField>

<ParamField type="JSON">
  LLM-generated visualization specification.
</ParamField>

<ParamField type="JSON">
  Highcharts configuration object for rendering charts. It contains the actual data as well the chart spec. See the [Highcharts API Reference](https://api.highcharts.com/highcharts/) for complete documentation on available options.
</ParamField>

## Related operations

<CardGroup>
  <Card title="VisualizationType Enum" icon="chart-bar" href="/integrations/graphql-api/objects/visualization-type">
    Available visualization types
  </Card>

  <Card title="DeltaElement Schema" icon="cube" href="/integrations/graphql-api/objects/delta-element">
    Container for visualizations
  </Card>
</CardGroup>


# VisualizationType
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/visualization-type



This page describes the types of visualizations used for displaying data.

The following table lists the available visualization types along with their corresponding descriptions.

| **Value**                  | **Description**                       |
| -------------------------- | ------------------------------------- |
| `BAR_CHART`                | Horizontal bar chart                  |
| `STACKED_BAR_CHART`        | Stacked horizontal bar chart          |
| `STACKED_100_BAR_CHART`    | 100% stacked horizontal bar chart     |
| `COLUMN_CHART`             | Vertical column chart                 |
| `STACKED_COLUMN_CHART`     | Stacked vertical column chart         |
| `STACKED_100_COLUMN_CHART` | 100% stacked vertical column chart    |
| `LINE_CHART`               | Line chart for trends over time       |
| `AREA_CHART`               | Area chart with filled regions        |
| `STACKED_AREA_CHART`       | Stacked area chart                    |
| `SCATTER_CHART`            | Scatter plot for correlation analysis |
| `FUNNEL_CHART`             | Funnel chart for conversion analysis  |
| `PIE_CHART`                | Pie chart for proportional data       |
| `FORECAST_CHART`           | Chart with forecasting capabilities   |
| `POLAR_CHART`              | Polar coordinate chart                |
| `SPIDER_CHART`             | Spider/radar chart                    |
| `HEATMAP_CHART`            | Heatmap for density visualization     |
| `TABLE`                    | Tabular data display                  |
| `TEXT`                     | Plain text display                    |
| `UNKNOWN_VISUALIZATION`    | Unknown or unspecified type           |
| `MAP`                      | Geographic map visualization          |
| `LLM_GENERATED_CHART`      | AI-generated custom chart             |

## Related operations

<CardGroup>
  <Card title="Visualization Schema" icon="chart-bar" href="/integrations/graphql-api/objects/visualization">
    Full visualization object structure
  </Card>
</CardGroup>


# VizConfig
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/viz-config



This page describes the VizConfig object that represents the schema for domain visualization configuration.

## VizConfig

<ParamField type="Boolean!">
  Whether to always use compact number formatting in visualizations.
</ParamField>

<ParamField type="Boolean!">
  Whether to show the data panel by default in visualizations.
</ParamField>

<ParamField type="Boolean!">
  Whether to show the domain description on the search page.
</ParamField>

<ParamField type="Boolean!">
  Whether to disable data previews for explorer users.
</ParamField>

<ParamField type="Boolean!">
  Whether to enable file download for explorer users.
</ParamField>

<ParamField type="Boolean!">
  Whether to always show full number text instead of abbreviated values.
</ParamField>

<ParamField type="DataLabelMode">
  Default data label mode for visualizations. See [DataLabelMode](/integrations/graphql-api/objects/data-label-mode).
</ParamField>

## Related operations

<CardGroup>
  <Card title="DomainModel Object" icon="folder" href="/integrations/graphql-api/objects/domain-model">
    Parent domain structure
  </Card>

  <Card title="DataLabelMode Enum" icon="list" href="/integrations/graphql-api/objects/data-label-mode">
    Data label display modes
  </Card>
</CardGroup>


# Widget Layout
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/widget-layout



This page describes the WidgetLayout object that defines the positioning and sizing of dashboard widgets.

## WidgetLayout

<ParamField type="Int!">
  Height of the widget in grid units.
</ParamField>

<ParamField type="Int!">
  Width of the widget in grid units.
</ParamField>

<ParamField type="Int!">
  Top position of the widget in grid coordinates.
</ParamField>

<ParamField type="Int!">
  Left position of the widget in grid coordinates.
</ParamField>

## Related operations

<CardGroup>
  <Card title="DashboardWidget Object" icon="chart-bar" href="/integrations/graphql-api/objects/dashboard-widget">
    Widget that uses this layout
  </Card>

  <Card title="WidgetLayoutInput Object" icon="pen-to-square" href="/integrations/graphql-api/objects/widget-layout-input">
    Input version for creating/updating layouts
  </Card>
</CardGroup>


# Widget Layout Input
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/widget-layout-input



This page describes the WidgetLayoutInput object used for creating and updating widget layouts.

## WidgetLayoutInput

<ParamField type="Int!">
  Height of the widget in grid units.
</ParamField>

<ParamField type="Int!">
  Width of the widget in grid units.
</ParamField>

<ParamField type="Int!">
  Top position of the widget in grid coordinates.
</ParamField>

<ParamField type="Int!">
  Left position of the widget in grid coordinates.
</ParamField>

## Related operations

<CardGroup>
  <Card title="WidgetLayout Object" icon="table-layout" href="/integrations/graphql-api/objects/widget-layout">
    Output version of layout
  </Card>

  <Card title="DashboardWidgetInput Object" icon="chart-bar" href="/integrations/graphql-api/objects/dashboard-widget-input">
    Input object that uses WidgetLayoutInput
  </Card>
</CardGroup>


# Widget Type
Source: https://docs.wisdom.ai/integrations/graphql-api/objects/widget-type



This page describes the WidgetType enum that defines the type of content in a dashboard widget.

## WidgetType

| Value                       | Description                   |
| --------------------------- | ----------------------------- |
| `WIDGET_TYPE_UNKNOWN`       | Unknown widget type           |
| `WIDGET_TYPE_VISUALIZATION` | Chart or table visualization  |
| `WIDGET_TYPE_MARKDOWN`      | Rich text content             |
| `WIDGET_TYPE_SUMMARY`       | Summary or aggregated content |

## Related operations

<CardGroup>
  <Card title="DashboardWidget Object" icon="chart-bar" href="/integrations/graphql-api/objects/dashboard-widget">
    Widget with type field
  </Card>

  <Card title="DashboardWidgetInput Object" icon="pen-to-square" href="/integrations/graphql-api/objects/dashboard-widget-input">
    Input object with widget type
  </Card>
</CardGroup>


# Exchange Access Token
Source: https://docs.wisdom.ai/integrations/graphql-api/queries/auth/exchange-access-token



The `exchangeAccessToken` query exchanges a dedicated access key for a JWT token that can be used to authenticate subsequent GraphQL API requests.

<Warning>
  **Deprecation Notice**\
  For embedding use cases, use the [Impersonate User](/integrations/graphql-api/mutations/auth/impersonate-user) API instead, which provides better security and user context.
</Warning>

## Signature

```graphql theme={null}
exchangeAccessToken(accessToken: String!): String!
```

## Parameters

<ParamField type="String!">
  The dedicated access key provided by WisdomAI for your organization. Contact `support@askwisdom.ai` to obtain your access key.
</ParamField>

## Response

Returns a JWT token as a string that should be used in the `Authorization` header for subsequent API requests.

## Usage example

```graphql theme={null}
query ExchangeAccessToken($accessToken: String!) {
  exchangeAccessToken(accessToken: $accessToken)
}
```

```bash theme={null}
curl -X POST https://{ACCOUNT}.askwisdom.ai/graphql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query ExchangeAccessToken($accessToken: String!) { exchangeAccessToken(accessToken: $accessToken) }",
    "variables": {
      "accessToken": "your-access-key-here"
    }
  }'
```

<Info>
  JWT tokens have a limited lifetime. You will need to exchange your access key for a new JWT token periodically.
</Info>

## Next steps

<CardGroup>
  <Card title="GraphQL API Overview" icon="code" href="/integrations/graphql-api/GraphQL-API">
    Complete GraphQL API authentication guide
  </Card>

  <Card title="Impersonate User" icon="user" href="/integrations/graphql-api/mutations/auth/impersonate-user">
    Recommended API for embedding use cases
  </Card>
</CardGroup>


# Connection
Source: https://docs.wisdom.ai/integrations/graphql-api/queries/connection/connection



Retrieve detailed information about a specific data source connection, including its last job run and last successful job run.

## Signature

```graphql theme={null}
connection(id: ID!): Connection!
```

<Note>
  This query can only be executed by an administrator or a data administrator of the specific connection ID.
</Note>

## Arguments

<ParamField type="ID!">
  The unique identifier of the connection to retrieve.
</ParamField>

## Response

Returns a `Connection` object containing connection details and status information. See [Connection](/integrations/graphql-api/objects/connection) schema.

## Usage example

```graphql theme={null}
query GetConnectionRefreshStatus($id: ID!) {
  connection(id: $id) {
    id
    status {
      lastRun {
        status
        startedAt
        endedAt
        conciseErrorMessage
      }
      lastSuccessfulRun {
        status
        endedAt
      }
    }
  }
}
```

<RequestExample>
  ```bash Request theme={null}
  curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <jwt_token>" \
    -d '{
      "query": "query GetConnection($id: ID!) { connection(id: $id) { id details { name connectionType } status { lastRun { status endedAt } } } }",
      "variables": {
        "id": "et-connection-id-here"
      }
    }' \
    https://{ACCOUNT}.askwisdom.ai/graphql
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "data": {
      "connection": {
        "id": "et-connection-id-here",
        "details": {
          "name": "Snowflake Jan07",
          "connectionType": "SNOWFLAKE"
        },
        "status": {
          "lastRun": {
            "status": "JOB_RUN_STATUS_SUCCESS",
            "endedAt": "2025-07-21T21:45:54.931+00:00"
          }
        }
      }
    }
  }
  ```
</ResponseExample>

## Next steps

<CardGroup>
  <Card title="Refresh Connection" icon="arrows-rotate" href="/integrations/graphql-api/mutations/connection/refresh-connection">
    Trigger metadata refresh for connections
  </Card>

  <Card title="Connection Schema" icon="database" href="/integrations/graphql-api/objects/connection">
    Learn about connection object structure
  </Card>

  <Card title="JobStatus Schema" icon="clock" href="/integrations/graphql-api/objects/job-status">
    Understand job execution status tracking
  </Card>
</CardGroup>


# Dashboard
Source: https://docs.wisdom.ai/integrations/graphql-api/queries/dashboard/dashboard



The `dashboard` query retrieves detailed information about a specific dashboard by its unique identifier.

## Signature

```graphql theme={null}
dashboard(id: String!, scope: DashboardScope!, version: String): Dashboard!
```

## Arguments

<ParamField type="String!">
  The unique identifier of the dashboard to retrieve.
</ParamField>

<ParamField type="DashboardScope!">
  The access level required for the dashboard. See [DashboardScope](/integrations/graphql-api/objects/dashboard-scope).
</ParamField>

<ParamField type="String">
  Optional version identifier for retrieving a specific historical snapshot of the dashboard.
</ParamField>

## Response

Returns a `Dashboard` object containing the complete dashboard configuration and metadata. See [Dashboard](/integrations/graphql-api/objects/dashboard) for the schema.

## Usage example

This example shows how to retrieve a dashboard with editor access:

```graphql theme={null}
query GetDashboard($id: String!, $scope: DashboardScope!) {
  dashboard(id: $id, scope: $scope) {
    id
    name
    description
    widgets {
      id
      title
      nlQuery
      widgetType
      layout {
        top
        left
        width
        height
      }
      visualization {
        id
        title
        type
      }
      summaryWidgetConfig{
        customInstructions
      }
    }
    filters {
      id
      parsedFilter {
        filterId
        operator
        lhs {
          displayName
        }
        rhs {
          literal {
            flattened {
              literal {
                value
              }
            }
          
          }
        }
      }
    }
    accessLevel
  }
}
```

<RequestExample>
  ```bash Request theme={null}
  curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <jwt_token>" \
    -d '{
      "query": "query GetDashboard($id: String!, $scope: DashboardScope!) { dashboard(id: $id, scope: $scope) { id name description widgets { id title layout { top left width height } } accessLevel } }",
      "variables": {
        "id": "dashboard_123456789",
        "scope": "EDITOR"
      }
    }' \
    https://{ACCOUNT}.askwisdom.ai/graphql
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "data": {
      "dashboard": {
        "id": "dashboard_123456789",
        "name": "Sales Performance Dashboard",
        "description": "Monthly sales metrics and KPIs",
        "widgets": [
          {
            "id": "widget_987654321",
            "title": "Total Sales",
            "layout": {
              "top": 0,
              "left": 0,
              "width": 6,
              "height": 4
            }
          },
          {
            "id": "widget_96f27a852f55",
            "title": " ",
            "nlQuery": "",
            "widgetType": "WIDGET_TYPE_SUMMARY",
            "layout": {
              "top": 1,
              "left": 0,
              "width": 12,
              "height": 3,
            },
            "visualization": null,
            "summaryWidgetConfig": {
              "customInstructions": "User guidelines:Generate Short Summary",
            },
          },
        ],
        "filters": [
          {
            "id": "dashboard_123456789-filter_1234",
            "parsedFilter": {
              "filterId": "filter_1234",
              "operator": "FUNC_ILIKE",
              "lhs": {
                "displayName": "acc.ACCOUNT_NAME",
                "__typename": "LHS"
              },
              "rhs": {
                "literal": {
                  "flattened": [
                    {
                      "literal": {
                        "value": "\"%Account%\"",
                      },
                    }
                  ],
                },
              },
            },
          }
        ],
        "accessLevel": "EDITOR"
      }
    }
  }
  ```
</ResponseExample>

## Next steps

<CardGroup>
  <Card title="Dashboards Query" icon="list" href="/integrations/graphql-api/queries/dashboard/dashboards">
    Retrieve multiple dashboards
  </Card>

  <Card title="Update Dashboard" icon="pen-to-square" href="/integrations/graphql-api/mutations/dashboard/update-dashboard">
    Modify dashboard properties
  </Card>

  <Card title="Dashboard Object" icon="folder" href="/integrations/graphql-api/objects/dashboard">
    Complete dashboard schema
  </Card>
</CardGroup>


# Dashboards
Source: https://docs.wisdom.ai/integrations/graphql-api/queries/dashboard/dashboards



The `dashboards` query retrieves a list of dashboards accessible to the current user, with optional filtering by domain and owner.

## Signature

```graphql theme={null}
dashboards(scope: DashboardScope!, domainId: String, ownerId: String): DashboardsResponse!
```

## Arguments

<ParamField type="DashboardScope!">
  The access level to filter dashboards by. See [DashboardScope](/integrations/graphql-api/objects/dashboard-scope).
</ParamField>

<ParamField type="String">
  Optional filter to retrieve only dashboards associated with a specific domain.
</ParamField>

<ParamField type="String">
  Optional filter to retrieve only dashboards owned by a specific user.
</ParamField>

## Response

Returns a `DashboardsResponse` object containing a list of accessible dashboards. See [DashboardsResponse](/integrations/graphql-api/objects/dashboards-response) for the schema.

## Usage example

This example shows how to retrieve all dashboards with viewer access:

```graphql theme={null}
query GetDashboards($scope: DashboardScope!) {
  dashboards(scope: $scope) {
    nodes {
      id
      name
      createdAt
      domains {
        id
        name
      }
      owner {
        id
        displayName
      }
      accessLevel
    }
  }
}
```

<RequestExample>
  ```bash Request theme={null}
  curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <jwt_token>" \
    -d '{
      "query": "query GetDashboards($scope: DashboardScope!) { dashboards(scope: $scope) { nodes { id name createdAt domains { id name } owner { id displayName } accessLevel } } }",
      "variables": {
        "scope": "VIEWER"
      }
    }' \
    https://{ACCOUNT}.askwisdom.ai/graphql
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "data": {
      "dashboards": {
        "nodes": [
          {
            "id": "dashboard_123456789",
            "name": "Sales Performance Dashboard",
            "createdAt": "2024-01-15T10:30:00Z",
            "domains": [
              {
                "id": "domain_987654321",
                "name": "Sales Analytics"
              }
            ],
            "owner": {
              "id": "user_456789123",
              "displayName": "John Doe"
            },
            "accessLevel": "EDITOR"
          }
        ]
      }
    }
  }
  ```
</ResponseExample>

## Next steps

<CardGroup>
  <Card title="Dashboard Query" icon="search" href="/integrations/graphql-api/queries/dashboard/dashboard">
    Retrieve a specific dashboard
  </Card>

  <Card title="Create Dashboard" icon="plus" href="/integrations/graphql-api/mutations/dashboard/create-dashboard">
    Create a new dashboard
  </Card>

  <Card title="DashboardsResponse Object" icon="folder" href="/integrations/graphql-api/objects/dashboards-response">
    Complete response schema
  </Card>
</CardGroup>


# Current User
Source: https://docs.wisdom.ai/integrations/graphql-api/queries/user/current-user



Retrieve information about the currently authenticated user and their account details.

## currentUser

Retrieves detailed information about the currently authenticated user, including profile data, preferences, and permissions.

### Signature

```graphql theme={null}
currentUser: User!
```

### Parameters

This query takes no parameters and returns information for the currently authenticated user based on the provided bearer token.

### Response type

Returns a `User` object containing comprehensive user information. See the [User Objects](/integrations/graphql-api/objects/user) documentation for complete field definitions.

## Authentication

User queries require authentication via bearer token. Include your API token in the Authorization header:

```
Authorization: Bearer YOUR_API_TOKEN
```

## Next steps

<CardGroup>
  <Card title="User Objects" icon="user" href="/integrations/graphql-api/objects/user">
    Complete reference for user-related objects
  </Card>
</CardGroup>


# List Users
Source: https://docs.wisdom.ai/integrations/graphql-api/queries/user/list-users



The `listUsers` query returns users in a workspace along with their attributes and role assignments. Use it to look up user IDs before calling [impersonateUser](/integrations/graphql-api/mutations/auth/impersonate-user) or [setUserAttributes](/integrations/graphql-api/mutations/user/set-user-attributes).

## Signature

```graphql theme={null}
listUsers(workspaceId: ID): [User!]!
```

## Parameters

<ParamField type="ID">
  Filters results to a specific workspace. Required for multi-workspace deployments.
</ParamField>

## Response

Returns an array of `User` objects. See [User](/integrations/graphql-api/objects/user) for the full schema. The fields most relevant to user management are:

<ParamField type="ID!">
  The user's unique ID. Pass this to `impersonateUser`, `setUserAttributes`, or `deleteUsersFromWorkspace`.
</ParamField>

<ParamField type="String!">
  The user's email address.
</ParamField>

<ParamField type="[UserAttribute!]">
  Key-value pairs associated with the user. Each entry includes:

  * `key` — attribute name
  * `value` — attribute value
  * `source` — either `DATABASE` (set via API) or `JWT` (from SSO claims, read-only)

  See [User attributes](/integrations/user-management/user-attributes) for how these sources differ.
</ParamField>

<ParamField type="[RoleAssignment!]">
  The roles assigned to the user and their scope.
</ParamField>

## Usage example

```graphql theme={null}
query ListUsers($workspaceId: ID) {
  listUsers(workspaceId: $workspaceId) {
    id
    email
    userAttributes {
      key
      value
      source
    }
    roleAssignments {
      roleId
      scopes
    }
  }
}
```

<RequestExample>
  ```bash Request theme={null}
  curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <access_token>" \
    -d '{
      "query": "query ListUsers($workspaceId: ID) { listUsers(workspaceId: $workspaceId) { id email userAttributes { key value source } roleAssignments { roleId scopes } } }",
      "variables": {
        "workspaceId": "workspace_123"
      }
    }' \
    https://{ACCOUNT}.askwisdom.ai/graphql
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "data": {
      "listUsers": [
        {
          "id": "user_abc123",
          "email": "alice@yourcompany.com",
          "userAttributes": [
            { "key": "account_id", "value": "acct_456", "source": "DATABASE" },
            { "key": "department", "value": "finance", "source": "JWT" }
          ],
          "roleAssignments": [
            { "roleId": "00000000-0000-0000-0000-000000000003", "scopes": ["{{DOMAIN_ID}}"] }
          ]
        }
      ]
    }
  }
  ```
</ResponseExample>

## Related articles

<CardGroup>
  <Card title="Impersonate user" icon="user-secret" href="/integrations/graphql-api/mutations/auth/impersonate-user">
    Use the user ID to start an embedded session
  </Card>

  <Card title="Set user attributes" icon="tag" href="/integrations/graphql-api/mutations/user/set-user-attributes">
    Update DATABASE-sourced attributes on a user
  </Card>

  <Card title="Delete users from workspace" icon="user-minus" href="/integrations/graphql-api/mutations/user/delete-users-from-workspace">
    Remove users from a workspace
  </Card>
</CardGroup>


# Dashboard Summary
Source: https://docs.wisdom.ai/integrations/graphql-api/subscriptions/dashboard-summary



The `dashboardSummary` subscription allows you to generate summary of a dashboard, based on the instructions provided to it

## Signature

```graphql theme={null}
dashboardSummary(
    auth: SubscriptionAuthInput!
    id: String!
    idempotencyKey: String!
    customInstructions: String
    summaryType: DashboardSummaryType
  ): DashboardSummaryDiff! 
```

## Arguments

<ParamField type="SubscriptionAuthInput!">
  Authentication credentials for the subscription. See [SubscriptionAuthInput](/integrations/graphql-api/objects/subscription-auth-input).
</ParamField>

<ParamField type="String!">
  The unique identifier of the dashboard whose summary is to be generated.
</ParamField>

<ParamField type="String!">
  The random string to be passed to avoid duplicate calls to the server.
</ParamField>

<ParamField type="String">
  The instructions to be followed while generating summary.
</ParamField>

<ParamField type="DashboardSummaryType">
  The type of summary to be generated. See [DashboardSummaryType](/integrations/graphql-api/objects/dashboard-summary-type).
</ParamField>

## Response

Returns an array of `DashboardSummaryDiff` objects representing conversation updates. See [DashboardSummaryDiff](/integrations/graphql-api/objects/dashboard-summary-diff) for the schema.

## Usage example

A very simple example to get you started is to do the following:

```graphql theme={null}
 subscription DashboardSummary(
    $auth: SubscriptionAuthInput!,
    $id: String!,
    $idempotencyKey: String!,
    $customInstructions: String,
    $summaryType: DashboardSummaryType,
  ) {
    dashboardSummary(
      auth: $auth,
      id: $id,
      idempotencyKey: $idempotencyKey,
      customInstructions: $customInstructions,
      summaryType: $summaryType,
    ) {
      chunk
    }
  }
```

<RequestExample>
  ```bash Request theme={null}
  wscat -c wss://{ACCOUNT}.askwisdom.ai/graphql \
    -H "Authorization: Bearer <jwt_token>" \
    -s graphql-ws \
    --execute '{
      "type": "start",
      "payload": {
        "query": "subscription DashboardSummary($auth: SubscriptionAuthInput!,$id: String!,$idempotencyKey: String!, $customInstructions: String,$summaryType: DashboardSummaryType) { dashboardSummary(auth: $auth, id: $id, idempotencyKey: $idempotencyKey, customInstructions: $customInstructions, summaryType: $summaryType) { chunk }",
        "variables": {
          "auth": {
            "token": "<jwt_token>"
          },
          "id": "dash_1234",
          "idempotencyKey": "abc",
          "customInstructions": "User guidelines: ....",
        }
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "data": {
      "dashboardSummary": [
        {
          "chunk": "The summary of",
        }
      ]
    }
  }
  ```
</ResponseExample>

## Related operation

<CardGroup>
  <Card title="DashboardSummaryDiff Schema" icon="cube" href="/integrations/graphql-api/objects/dashboard-summary-diff">
    Learn about dashboard summary diff
  </Card>
</CardGroup>


# Subscribe Conversation
Source: https://docs.wisdom.ai/integrations/graphql-api/subscriptions/subscribe-conversation



The `subscribeConversation` subscription allows you to listen for real-time updates to a conversation, including new messages and response streams, via a WebSocket-based subscription model.

## Signature

```graphql theme={null}
subscribeConversation(
  auth: SubscriptionAuthInput!
  conversationId: String!
): [ConversationUpdateOneOf!]!
```

## Arguments

<ParamField type="SubscriptionAuthInput!">
  Authentication credentials for the subscription. See [SubscriptionAuthInput](/integrations/graphql-api/objects/subscription-auth-input).
</ParamField>

<ParamField type="String!">
  The unique identifier of the conversation to subscribe to.
</ParamField>

## Response

Returns an array of `ConversationUpdateOneOf` objects representing conversation updates. See [ConversationUpdateOneOf](/integrations/graphql-api/objects/conversation-update-one-of) for the schema.

## Usage example

A very simple example to get you started is to do the following:

```graphql theme={null}
subscription SubscribeConversation(
  $auth: SubscriptionAuthInput!
  $conversationId: String!
) {
  subscribeConversation(
    auth: $auth
    conversationId: $conversationId
  ) {
    assistantMessageSent {
      id
      body {
        ops {
          insert {
            text
            visualization {
              id
              title
              type
              highchartsOptions
            }
          }
        }
      }
      sender
      createdAt
    }
    assistantResponseDiff {
      bodyDiff {
        ops {
          insert {
            text
          }
          visualization {
            id
            title
            type
            highchartsOptions
          }
        }
      }
      sender
      inProgress
    }
    assistantResponseCancelled
  }
}
```

<RequestExample>
  ```bash Request theme={null}
  wscat -c wss://{ACCOUNT}.askwisdom.ai/graphql \
    -H "Authorization: Bearer <jwt_token>" \
    -s graphql-ws \
    --execute '{
      "type": "start",
      "payload": {
        "query": "subscription SubscribeConversation($auth: SubscriptionAuthInput!, $conversationId: String!) { subscribeConversation(auth: $auth, conversationId: $conversationId) { assistantMessageSent { id body { ops { insert { text } } } sender createdAt } assistantResponseDiff { bodyDiff { ops { insert { text } } } sender inProgress } assistantResponseCancelled } }",
        "variables": {
          "auth": {
            "token": "<jwt_token>"
          },
          "conversationId": "conv_123456789"
        }
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "data": {
      "subscribeConversation": [
        {
          "assistantMessageSent": {
            "id": "msg_987654321",
            "body": {
              "ops": [
                {
                  "insert": {
                    "text": "Here's the analysis you requested:"
                  }
                }
              ]
            },
            "sender": "ASSISTANT",
            "createdAt": "2024-01-15T10:30:00Z"
          },
          "assistantResponseDiff": null,
          "assistantResponseCancelled": null
        }
      ]
    }
  }
  ```
</ResponseExample>

## Related operation

<CardGroup>
  <Card title="ConversationUpdateOneOf Schema" icon="cube" href="/integrations/graphql-api/objects/conversation-update-one-of">
    Learn about conversation update types
  </Card>
</CardGroup>


# MCP Server
Source: https://docs.wisdom.ai/integrations/mcp-server/MCP-Server



WisdomAI provides a hosted [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that lets you connect AI tools, such as Claude, Cursor, VS Code, and ChatGPT, directly to your WisdomAI domains. Once connected, you can ask natural language questions about your data and receive structured responses including text, tables, and interactive charts.

## MCP Endpoint

The WisdomAI MCP Server is available at a single endpoint:

```text theme={null}
https://{ACCOUNT}.wisdom.ai/mcp
```

Replace `{ACCOUNT}` with your WisdomAI account subdomain.

<Note>
  The MCP endpoint must match the domain you use to log in.

  * If you log in via `{account}.wisdom.ai`, use `https://{ACCOUNT}.wisdom.ai/mcp`
  * If you log in via `{account}.askwisdom.ai`, use `https://{ACCOUNT}.askwisdom.ai/mcp`
</Note>

## Connect Wisdom's MCP server to your client

Add the WisdomAI MCP Server to your preferred AI client using the configuration below.

<Tabs>
  <Tab title="Claude Code">
    Run this command in your terminal:

    ```bash theme={null}
    claude mcp add --transport http wisdomai https://{ACCOUNT}.wisdom.ai/mcp
    ```

    Then authenticate by running `/mcp` in Claude Code and following the OAuth flow.
  </Tab>

  <Tab title="Cursor">
    Add the following to your `~/.cursor/mcp.json` file:

    ```json theme={null}
    {
      "mcpServers": {
        "wisdomai": {
          "url": "https://{ACCOUNT}.wisdom.ai/mcp"
        }
      }
    }
    ```
  </Tab>

  <Tab title="VS Code">
    Add the following to your VS Code MCP settings (`.vscode/mcp.json`):

    ```json theme={null}
    {
      "servers": {
        "wisdomai": {
          "type": "http",
          "url": "https://{ACCOUNT}.wisdom.ai/mcp"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Other Clients">
    For any MCP-compatible client, use the following configuration:

    | Transport                         | URL                               |
    | :-------------------------------- | :-------------------------------- |
    | **Streamable HTTP** (recommended) | `https://{ACCOUNT}.wisdom.ai/mcp` |

    Most clients accept a JSON configuration in this format:

    ```json theme={null}
    {
      "mcpServers": {
        "wisdomai": {
          "url": "https://{ACCOUNT}.wisdom.ai/mcp"
        }
      }
    }
    ```

    If your client does not support remote HTTP connections directly, use the `mcp-remote` proxy:

    ```json theme={null}
    {
      "mcpServers": {
        "wisdomai": {
          "command": "npx",
          "args": ["-y", "mcp-remote", "https://{ACCOUNT}.wisdom.ai/mcp"]
        }
      }
    }
    ```
  </Tab>
</Tabs>

<Note>
  Replace `{ACCOUNT}` with your WisdomAI account url above.
</Note>

## Authentication

When you first connect, your client will prompt you to:

1. Log in with your WisdomAI account.
2. Accept the OAuth authorization.
3. Grant access to the necessary permissions.

The server implements **OAuth 2.1** with **Dynamic Client Registration (DCR)** and **Proof Key for Code Exchange (PKCE)**, following the [MCP Authorization specification](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization). This means:

* **No manual setup required**: clients register automatically.
* **Secure token binding**: tokens are scoped to your MCP session.
* **Session continuity**: each session maintains its own context and can handle multiple requests with the same token.

<Accordion title="OAuth Discovery Endpoints">
  The server exposes standard OAuth discovery endpoints for clients that need them:

  * **Protected Resource Metadata**: `/.well-known/oauth-protected-resource`
  * **Authorization Server Metadata**: `/.well-known/oauth-authorization-server`

  The authorization server metadata endpoint returns the locations of additional endpoints, including:

  * **DCR**: `/register` (obtained from `registration_endpoint`)
  * **Authorization Endpoint**: `/authorize` (obtained from `authorization_endpoint`)
  * **Token Endpoint**: `/token` (obtained from `token_endpoint`)

  MCP clients should query the `/.well-known/oauth-authorization-server` endpoint to discover the actual URLs rather than assuming fixed paths.
</Accordion>

## Available tools

Once connected, the following tools are available:

| Tool                                                            | Description                                                                                             |
| :-------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------ |
| [**chat**](/integrations/mcp-server/tools/chat)                 | Ask natural-language questions about your data domains. Returns text, tables, and chart visualizations. |
| [**list-domains**](/integrations/mcp-server/tools/list-domains) | Discover available domains and their IDs before making queries.                                         |
| [**echo**](/integrations/mcp-server/tools/echo)                 | Test connectivity and verify the request/response flow is working.                                      |

## Example prompts

Once connected, try these prompts to start using WisdomAI from your AI client:

* `What domains are available in WisdomAI?`
* `Show me total revenue by region as a table`
* `What are the top 5 products by sales this quarter?`
* `Visualize monthly active users over the last 12 months`
* `What can I ask about the Sales domain?`

## Test with the Inspector

You can test the WisdomAI MCP Server using the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector):

1. Install and launch the MCP Inspector:
   ```bash theme={null}
   npx @modelcontextprotocol/inspector
   ```
2. In the Inspector, enter your MCP server URL:
   ```text theme={null}
   https://{ACCOUNT}.wisdom.ai/mcp
   ```
3. Click **Connect**. The Inspector will automatically handle the OAuth authorization flow.
4. Once connected, click **List Tools** to see the available tools.
5. Select a tool (for example, **list-domains**) and click **Call** to test it.

The Inspector provides an interactive interface to test tool calls, inspect responses, and debug authentication.

## Troubleshooting

| Issue                      | Resolution                                                                                                                        |
| :------------------------- | :-------------------------------------------------------------------------------------------------------------------------------- |
| OAuth authentication fails | Ensure your client supports OAuth. Try reauthenticating using your client's MCP management flow.                                  |
| Tools not appearing        | Verify that authentication completed successfully and that you have access to at least one WisdomAI domain.                       |
| Connection timeout         | Check that the server URL is correct (`https://{ACCOUNT}.wisdom.ai/mcp`) and that your network allows outbound HTTPS connections. |
| Empty responses from chat  | Make sure you are providing a valid `domainId`. Use the **list-domains** tool first to find available domain IDs.                 |

## Next steps

<CardGroup>
  <Card title="Connected Apps" icon="plug" href="/settings/connected-apps">
    Sign in to OAuth-secured MCP server connections an admin has added.
  </Card>

  <Card title="API Keys" icon="key" href="/settings/api-keys">
    Create personal bearer tokens for programmatic access.
  </Card>
</CardGroup>

<Info>
  For any queries or support, contact our team at [**support@askwisdom.ai**](mailto:support@askwisdom.ai).
</Info>


# Chat Tool
Source: https://docs.wisdom.ai/integrations/mcp-server/tools/chat



The `chat` tool is the primary interface for interacting with WisdomAI's powerful data analysis capabilities. It accepts natural language questions and returns structured responses including text explanations, data tables, and interactive visualizations.

## Tool signature

```json theme={null}
{
  "name": "chat",
  "description": "Ask WisdomAI a question",
  "inputSchema": {
    "message": "string",
    "domainId": "string",
    "streaming": "boolean (optional, default: false)",
    "conversationId": "string (optional)"
  },
  "outputSchema": {
    "content": "Array<ContentItem>"
  }
}
```

## Parameters

<ParamField type="string">
  The query to ask to WisdomAI
</ParamField>

<ParamField type="string">
  The unique identifier of the domain you wish to query.
</ParamField>

<ParamField type="boolean">
  Whether to enable streaming responses via [MCP notifications](https://modelcontextprotocol.io/docs/concepts/transports#notifications). When enabled, partial results are sent progressively via notifications.

  <Warning>
    Streaming support is currently in beta and the implementation may change in future versions.
  </Warning>
</ParamField>

<ParamField type="string">
  UUID for conversation continuity. Provide an existing conversation ID to continue a chat thread, or leave empty to start a new conversation. Providing an invalid conversation ID is equivalent to leaving it empty.
</ParamField>

## Response format

The chat tool returns structured content in the following format:

```typescript theme={null}
{
  structuredContent: {
    content: Array<ContentItem>;
  };
  _meta: {
    conversationId: string;
    streamed: boolean;
    totalUpdates?: number; // Only present for streaming responses
  };
}
```

## Content types

<ParamField type="object">
  Plain text responses and explanations

  ```typescript theme={null}
  {
    type: "text";
    text: string;
  }
  ```
</ParamField>

<ParamField type="object">
  Tabular data with column headers and structured rows

  ```typescript theme={null}
  {
    type: "table";
    title: string;
    columns: string[];
    data: string[][];
  }
  ```
</ParamField>

<ParamField type="object">
  Interactive visualizations with Highcharts configuration

  ```typescript theme={null}
  {
    type: "chart";
    chart_type: string;
    title: string;
    highChartsOptions: string; // JSON string
    url: string; // Image URL for static rendering
  }
  ```

  <Note>
    `highchartsOptions` also contain the actual data and can be sent as it is to the [highcharts](https://www.highcharts.com/) library/server to generate a visualization.
  </Note>

  <Warning>
    Image URL is valid for 1 hour from the time of generation.
  </Warning>
</ParamField>

## Streaming support (Beta)

When streaming is enabled, the server sends progressive updates via [MCP notifications](https://modelcontextprotocol.io/docs/concepts/transports#notifications) as content is generated.

### Notification format

Streaming updates are sent using the `chat/update` notification method:

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "chat/update",
  "params": {
    "conversationId": "string",
    "updateNumber": "number",
    "isPartial": "boolean",
    "content": "Array<ContentItem>"
  }
}
```

### Update frequency

The server throttles streaming updates to a maximum frequency of **once per second**.

### Notification parameters

<ParamField type="string">
  The conversation ID associated with the query
</ParamField>

<ParamField type="number">
  Sequential number indicating the order of this update (starts at 1)
</ParamField>

<ParamField type="boolean">
  Whether this is still a partial update (`true`) or the final result (`false`)
</ParamField>

<ParamField type="Array<ContentItem>">
  The current state of the response content, **including all previous and new content items**
</ParamField>

## Usage example

### Request

```json MCP Tool Call theme={null}
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "chat",
    "arguments": {
      "message": "show aws usage by service as table",
      "domainId": "ET_DOMAIN_id-here",
      "streaming": false
    }
  },
  "id": 1
}
```

### Response

```json Response theme={null}
{
  "jsonrpc": "2.0",
  "result": {
    "_meta": {
        "conversationId": "b46e69a9-97bf-4dde-9cfe-96fe48719c07",
        "streamed": false
    },
    "structuredContent": {
        "content": [
            {
                "type": "table",
                "title": "AWS Usage by Service Table",
                "columns": [
                    "name",
                    "total_usage"
                ],
                "data": [
                    [
                        "\"EC2\"",
                        "3875727"
                    ],
                    [
                        "\"S3\"",
                        "3719077"
                    ],
                    [
                        "\"RDS\"",
                        "3581600"
                    ],
                    [
                        "\"Lambda\"",
                        "1683598"
                    ]
                ]
            }
        ]
    }
  },
  "id": 1
}
```

<RequestExample>
  ```json MCP Tool Call with Streaming theme={null}
  {
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "chat",
      "arguments": {
        "message": "what can I ask",
        "domainId": "ET_DOMAIN_id-here",
        "streaming": true
      }
    },
    "id": 2
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Progressive Notifications and Final Response theme={null}
  // Notification 1 (partial)
  {
    "jsonrpc": "2.0",
    "method": "chat/update",
    "params": {
      "conversationId": "f2a5aefb-7538-4044-9684-b68dd8256014",
      "updateNumber": 1,
      "content": [
        {
          "type": "text",
          "text": "Here"
        }
      ],
      "isPartial": true
    }
  }

  // Notification 2 (partial)
  {
    "jsonrpc": "2.0",
    "method": "chat/update",
    "params": {
      "conversationId": "f2a5aefb-7538-4044-9684-b68dd8256014",
      "updateNumber": 3,
      "content": [
        {
          "type": "text",
          "text": "Here are some ideas of questions you can ask to explore AWS service usage data:\n\n1. [Show total AWS service usage by region](#ask)\n2. [Which company used the most AWS resources last month?](#ask)\n3. [Visualize service usage by category (compute, storage, etc.)](#ask)\n4. [Top 5 AWS services by overall usage](#ask)\n5. [Which regions see the highest demand for S3?](#ask)\n6. [Compare usage between two companies](#ask)\n7. [What are the most popular services for machine learning?](#ask)\n8. [Which companies have stopped using AWS recently?](#ask)\n9."
        }
      ],
      "isPartial": true
    }
  }

  // Notification 3 (final notification)
  {
    "jsonrpc": "2.0",
    "method": "chat/update",
    "params": {
      "conversationId": "f2a5aefb-7538-4044-9684-b68dd8256014",
      "updateNumber": 5,
      "content": [
        {
          "type": "text",
          "text": "Here are some ideas of questions you can ask to explore AWS service usage data:\n\n1. [Show total AWS service usage by region](#ask)\n2. [Which company used the most AWS resources last month?](#ask)\n3. [Visualize service usage by category (compute, storage, etc.)](#ask)\n4. [Top 5 AWS services by overall usage](#ask)\n5. [Which regions see the highest demand for S3?](#ask)\n6. [Compare usage between two companies](#ask)\n7. [What are the most popular services for machine learning?](#ask)\n8. [Which companies have stopped using AWS recently?](#ask)\n9. [Breakdown of service usage by industry](#ask)\n10. [How does EC2 usage vary across regions?](#ask)\n\nFeel free to pick any of these or ask your own custom questions!"
        }
      ],
      "isPartial": false
    }
  }

  // Final Tool Call Response
  {
    "jsonrpc": "2.0",
    "result": {
      "structuredContent": {
        "content": [
          {
            "type": "text",
            "text": "Here are some ideas of questions you can ask to explore AWS service usage data:\n\n1. [Show total AWS service usage by region](#ask)\n2. [Which company used the most AWS resources last month?](#ask)\n3. [Visualize service usage by category (compute, storage, etc.)](#ask)\n4. [Top 5 AWS services by overall usage](#ask)\n5. [Which regions see the highest demand for S3?](#ask)\n6. [Compare usage between two companies](#ask)\n7. [What are the most popular services for machine learning?](#ask)\n8. [Which companies have stopped using AWS recently?](#ask)\n9. [Breakdown of service usage by industry](#ask)\n10. [How does EC2 usage vary across regions?](#ask)\n\nFeel free to pick any of these or ask your own custom questions!",
          },
        ]
      },
      "_meta": {
        "conversationId": "f2a5aefb-7538-4044-9684-b68dd8256014",
        "streamed": true,
        "totalUpdates": 3
      }
    },
    "id": 2
  }
  ```
</ResponseExample>

## Next steps

<CardGroup>
  <Card title="List Domains Tool" icon="list" href="/integrations/mcp-server/tools/list-domains">
    Discover available domains before querying
  </Card>

  <Card title="Echo Tool" icon="signal-stream" href="/integrations/mcp-server/tools/echo">
    Simple tool for testing connectivity before using chat
  </Card>
</CardGroup>


# Echo Tool
Source: https://docs.wisdom.ai/integrations/mcp-server/tools/echo



The `echo` tool is a simple testing utility that echoes back the input message with an "Echo: " prefix. This tool is primarily used for testing MCP server connectivity and verifying that the request/response flow is working correctly.

<Note>
  This is a sample tool included for testing your client.
</Note>

## Parameters

<ParamField type="string">
  The message to echo back. This can be any text string.
</ParamField>

## Response format

<ParamField type="object">
  Structured version of the response with a `message` array containing the echoed text
</ParamField>

### Content structure

```typescript theme={null}
{
  structuredContent: {
    message: [
      {
        text: string
      }
    ]
  }
}
```

<RequestExample>
  ```json MCP Tool Call theme={null}
  {
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "echo",
      "arguments": {
        "message": "Hello, WisdomAI!"
      }
    },
    "id": 1
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "jsonrpc": "2.0",
    "result": {
      "structuredContent": {
        "message": [
          {
            "text": "Echo: Hello, WisdomAI!"
          }
        ]
      }
    },
    "id": 1
  }
  ```
</ResponseExample>

## Next steps

<CardGroup>
  <Card title="List Domains Tool" icon="list" href="/integrations/mcp-server/tools/list-domains">
    Discover available domains for querying
  </Card>

  <Card title="Chat Tool" icon="message" href="/integrations/mcp-server/tools/chat">
    Primary tool for data analysis and natural language querying
  </Card>

  <Card title="MCP Server Overview" icon="server" href="/integrations/mcp-server/MCP-Server">
    Return to MCP server overview
  </Card>
</CardGroup>


# List Domains Tool
Source: https://docs.wisdom.ai/integrations/mcp-server/tools/list-domains



The `list-domains` tool retrieves all domains accessible to the authenticated user. This tool is essential for discovering available data domains before making queries with the chat tool.

## Tool signature

```json theme={null}
{
  "name": "list-domains",
  "description": "List domains accessible to the user",
  "inputSchema": {},
  "outputSchema": {
    "domains": "Array<Domain>"
  }
}
```

## Parameters

This tool requires no input parameters. Authentication is handled automatically through the MCP session.

## Response format

The list-domains tool returns structured content with domain information:

```typescript theme={null}
{
  structuredContent: {
    domains: Array<{
      id: string;
      name: string;
      description: string;
    }>;
  };
}
```

## Domain object

<ParamField type="string">
  Unique identifier for the domain. Use this ID when making chat tool requests.
</ParamField>

<ParamField type="string">
  Human-readable name of the domain
</ParamField>

<ParamField type="string">
  Description of the domain's purpose and data content. May be empty for some domains.
</ParamField>

## Usage example

### Request

```json MCP Tool Call theme={null}
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "list-domains"
  },
  "id": 1
}
```

### Response

```json Response theme={null}
{
  "jsonrpc": "2.0",
  "result": {
    "structuredContent": {
      "domains": [
        {
          "id": "ET_DOMAIN_aws-usage",
          "name": "AWS Usage Analytics",
          "description": "AWS service usage data across regions and companies"
        },
        {
          "id": "ET_DOMAIN_sales-data",
          "name": "Sales Performance",
          "description": "Sales metrics, revenue data, and customer analytics"
        },
        {
          "id": "ET_DOMAIN_hr-metrics",
          "name": "HR Analytics",
          "description": "Employee data, performance metrics, and organizational insights"
        }
      ]
    }
  },
  "id": 1
}
```

## Common use cases

<CardGroup>
  <Card title="Domain Discovery" icon="search">
    List all available domains with their IDs before starting a chat
  </Card>

  <Card title="Access Validation" icon="shield-check">
    Verify which domains the current user can access
  </Card>

  <Card title="User Onboarding" icon="user-plus">
    Help new users understand available data sources
  </Card>
</CardGroup>

## Next steps

<CardGroup>
  <Card title="Chat Tool" icon="message" href="/integrations/mcp-server/tools/chat">
    Use domain IDs from this tool to query specific domains
  </Card>

  <Card title="MCP Server Overview" icon="server" href="/integrations/mcp-server/MCP-Server">
    Learn more about the MCP server architecture
  </Card>
</CardGroup>


# RBAC for Users
Source: https://docs.wisdom.ai/integrations/user-management/rbac



Embedded users inherit WisdomAI's role-based access control (RBAC) system. The role you assign when provisioning a user controls what they can see and do inside the embedded interface. There is no separate embed-specific permission layer.

<Note>
  Custom roles are not yet supported. You must use one of the built-in roles listed below.
</Note>

## How roles affect embedded views

Visibility of edit controls, dashboard creation buttons, and AI workstreams is determined by the user's role assignment. To **hide edit controls in an embedded dashboard**, assign the user the **Viewer** role. This role is pure read-only and cannot create or modify any resources.

<Note>
  For a full breakdown of what each role can access, see [Roles & permission reference](#roles--permission-reference) below.
</Note>

## Assigning a role at provisioning time

Pass the specific `roleId` in the `roleAssignments` array when calling `createUsers`. Role IDs are unique UUIDs.

```bash theme={null}
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
    "query": "mutation CreateUsers($input: CreateUsersInput!) { createUsers(input: $input) { status { code message } } }",
    "variables": {
      "input": {
        "emails": ["alice@yourcompany.com"],
        "workspaceID": "workspace_123",
        "roleAssignments": [
          {
            "roleId": "00000000-0000-0000-0000-000000000003",
            "scopes": ["domain_456"]
          }
        ]
      }
    }
  }' \
  https://{ACCOUNT}.wisdom.ai/graphql
```

## Role IDs

Role IDs are passed in the `roleAssignments` field when provisioning or updating users.

| Role             | ID                                     |
| ---------------- | -------------------------------------- |
| `ADMIN`          | `00000000-0000-0000-0000-000000000001` |
| `DATA_ADMIN`     | `00000000-0000-0000-0000-000000000004` |
| `EXPLORER`       | `00000000-0000-0000-0000-000000000002` |
| `BASIC_EXPLORER` | `00000000-0000-0000-0000-000000000015` |
| `VIEWER`         | `00000000-0000-0000-0000-000000000003` |
| `OBSERVER`       | `00000000-0000-0000-0000-000000000007` |

Role IDs are used in the `roleAssignments` field of the following mutations:

* [`createUsers`](/integrations/graphql-api/mutations/user/create-users) — assign a role when provisioning a new embedded user
* [`setUserAttributes`](/integrations/graphql-api/mutations/user/set-user-attributes) — update the role of an existing embedded user
* [`addScopeRoleAssignmentsForSharing`](/integrations/graphql-api/mutations/dashboard/add-scope-role-assignments-for-sharing) — grant a scoped role on a specific dashboard
* [`removeScopeRoleAssignmentsForSharing`](/integrations/graphql-api/mutations/dashboard/remove-scope-role-assignments-for-sharing) — remove a scoped role from a specific dashboard

## Roles & permission reference

The tables below show the full permission breakdown across all roles and resource types. Use these as a reference when deciding which role to assign for a given use case. For a description of what each role can do, see [Access Management](/manage-account/access-management).

<Note>
  In the API, **Story** refers to **Dashboards**. Roles labeled **Writer** grant edit access to existing resources but do not grant permission to create new ones.
</Note>

<Accordion title="Granular permissions">
  <Accordion title="Chat">
    | Permission               |  AD |  DA |  EX |  BE |  VI |  OB |
    | ------------------------ | :-: | :-: | :-: | :-: | :-: | :-: |
    | `chat:create`            |  ✅  |  ✅  |  ✅  |  ✅  |  ❌  |  ❌  |
    | `chat:execute-sql`       |  ✅  |  ✅  |  ✅  |  ✅  |  ❌  |  ❌  |
    | `chat:edit-sql`          |  ✅  |  ✅  |  ✅  |  ❌  |  ❌  |  ❌  |
    | `chat:expand-workstream` |  ✅  |  ✅  |  ✅  |  ❌  |  ❌  |  ❌  |
    | `chat:read-all`          |  ✅  |  ❌  |  ❌  |  ❌  |  ❌  |  ❌  |
  </Accordion>

  <Accordion title="Dashboard">
    | Permission         |  AD |  DA |  EX |  BE |  VI |  OB |
    | ------------------ | :-: | :-: | :-: | :-: | :-: | :-: |
    | `dashboard:create` |  ✅  |  ✅  |  ✅  |  ✅  |  ❌  |  ❌  |
    | `dashboard:clone`  |  ✅  |  ✅  |  ❌  |  ❌  |  ❌  |  ❌  |
    | `dashboard:read`   |  ✅  |  ✅  |  ❌  |  ❌  |  ✅  |  ❌  |
    | `dashboard:write`  |  ❌  |  ❌  |  ❌  |  ❌  |  ❌  |  ❌  |

    <Note>
      Users can always view, edit, and clone dashboards they created themselves or that have been shared with them.
    </Note>
  </Accordion>

  <Accordion title="Schedule">
    | Permission        |  AD |  DA |  EX |  BE |  VI |  OB |
    | ----------------- | :-: | :-: | :-: | :-: | :-: | :-: |
    | `schedule:create` |  ✅  |  ✅  |  ✅  |  ✅  |  ❌  |  ❌  |
    | `schedule:read`   |  ✅  |  ✅  |  ❌  |  ❌  |  ✅  |  ❌  |
    | `schedule:write`  |  ❌  |  ❌  |  ❌  |  ❌  |  ❌  |  ❌  |

    <Note>
      Users can always view and edit schedules they created themselves or that have been shared with them.
    </Note>
  </Accordion>

  <Accordion title="Agent">
    | Permission    |  AD |  DA |  EX |  BE |  VI |  OB |
    | ------------- | :-: | :-: | :-: | :-: | :-: | :-: |
    | `agent:read`  |  ✅  |  ✅  |  ✅  |  ✅  |  ✅  |  ❌  |
    | `agent:write` |  ✅  |  ✅  |  ❌  |  ❌  |  ❌  |  ❌  |

    <Note>
      Users can always view and edit agents they created themselves or that have been shared with them.
    </Note>
  </Accordion>

  <Accordion title="Connection">
    | Permission           |  AD |  DA |  EX |  BE |  VI |  OB |
    | -------------------- | :-: | :-: | :-: | :-: | :-: | :-: |
    | `connection:create`  |  ✅  |  ✅  |  ❌  |  ❌  |  ❌  |  ❌  |
    | `connection:read`    |  ✅  |  ✅  |  ❌  |  ❌  |  ❌  |  ❌  |
    | `connection:write`   |  ✅  |  ❌  |  ❌  |  ❌  |  ❌  |  ❌  |
    | `connection:delete`  |  ✅  |  ❌  |  ❌  |  ❌  |  ❌  |  ❌  |
    | `connection:refresh` |  ✅  |  ✅  |  ❌  |  ❌  |  ❌  |  ❌  |
    | `connection:list`    |  ✅  |  ✅  |  ❌  |  ❌  |  ❌  |  ❌  |
  </Accordion>

  <Accordion title="Domain">
    | Permission      |  AD |  DA |  EX |  BE |  VI |  OB |
    | --------------- | :-: | :-: | :-: | :-: | :-: | :-: |
    | `domain:create` |  ✅  |  ✅  |  ❌  |  ❌  |  ❌  |  ❌  |
    | `domain:list`   |  ✅  |  ✅  |  ❌  |  ❌  |  ❌  |  ❌  |
    | `domain:invite` |  ✅  |  ✅  |  ❌  |  ❌  |  ❌  |  ❌  |
  </Accordion>

  <Accordion title="IAM">
    | Permission        |  AD |  DA |  EX |  BE |  VI |  OB |
    | ----------------- | :-: | :-: | :-: | :-: | :-: | :-: |
    | `iam:read`        |  ✅  |  ✅  |  ✅  |  ✅  |  ✅  |  ✅  |
    | `iam:write`       |  ✅  |  ❌  |  ❌  |  ❌  |  ❌  |  ❌  |
    | `iam:delete`      |  ✅  |  ❌  |  ❌  |  ❌  |  ❌  |  ❌  |
    | `iam-scope:write` |  ✅  |  ✅  |  ✅  |  ✅  |  ❌  |  ❌  |
  </Accordion>

  <Accordion title="Workspace">
    | Permission         |  AD |  DA |  EX |  BE |  VI |  OB |
    | ------------------ | :-: | :-: | :-: | :-: | :-: | :-: |
    | `workspace:read`   |  ✅  |  ❌  |  ❌  |  ❌  |  ✅  |  ✅  |
    | `workspace:write`  |  ✅  |  ❌  |  ❌  |  ❌  |  ❌  |  ❌  |
    | `workspace:create` |  ❌  |  ❌  |  ❌  |  ❌  |  ❌  |  ❌  |
    | `workspace:delete` |  ❌  |  ❌  |  ❌  |  ❌  |  ❌  |  ❌  |
  </Accordion>
</Accordion>

<Accordion title="Permission reference">
  The table below describes what each API permission flag controls.

  | API permission           | Feature                       |
  | ------------------------ | ----------------------------- |
  | `chat:create`            | Ask questions                 |
  | `chat:execute-sql`       | Run SQL                       |
  | `chat:edit-sql`          | Edit SQL                      |
  | `chat:expand-workstream` | AI workstream                 |
  | `chat:read-all`          | View chat log                 |
  | `dashboard:create`       | Create dashboards             |
  | `dashboard:read`         | View dashboards               |
  | `dashboard:write`        | Edit dashboards               |
  | `dashboard:clone`        | Clone dashboards              |
  | `schedule:create`        | Create schedules              |
  | `schedule:read`          | View schedules                |
  | `schedule:write`         | Edit schedules                |
  | `agent:read`             | View agents                   |
  | `agent:write`            | Edit agents                   |
  | `connection:create`      | Create connections            |
  | `connection:read`        | View connections              |
  | `connection:write`       | Edit connection configuration |
  | `connection:delete`      | Delete connections            |
  | `connection:refresh`     | Refresh metadata              |
  | `connection:list`        | List connections              |
  | `domain:create`          | Create domains                |
  | `domain:list`            | List domains                  |
  | `domain:invite`          | Invite users to a domain      |
  | `iam:read`               | View users and roles          |
  | `iam:write`              | Manage users and roles        |
  | `iam:delete`             | Remove users and roles        |
  | `iam-scope:write`        | Assign scoped roles           |
  | `workspace:read`         | View workspace                |
  | `workspace:write`        | Edit workspace                |
</Accordion>

## Related articles

<CardGroup>
  <Card title="Create Users" icon="user-plus" href="/integrations/graphql-api/mutations/user/create-users">
    Provision embedded users with role assignments
  </Card>

  <Card title="Embed a Dashboard" icon="chart-bar" href="/integrations/embeddings/iframe/embed-a-dashboard">
    Use roles to control edit access in embedded dashboards
  </Card>
</CardGroup>


# User Attributes
Source: https://docs.wisdom.ai/integrations/user-management/user-attributes



User attributes are key-value pairs attached to a user that control how WisdomAI filters and personalizes data for their session. They are used for:

* **Parameterized connections**: matching a user's attributes against `credentialMappings.attributeMatch` to resolve the right data source credentials.
* **Row-level authorization**: referencing attributes in filter rules to restrict which rows a user can see.
* **Personalized data access**: passing session-specific context (e.g., a selected account or region) at impersonation time.

## Attribute sources

Every attribute has a `source` field that indicates where it came from.

| Source     | Set by                                   | Mutable via API | Description                                      |
| ---------- | ---------------------------------------- | :-------------: | ------------------------------------------------ |
| `DATABASE` | API (`createUsers`, `setUserAttributes`) |       Yes       | Persistent attributes stored against the user    |
| `JWT`      | SSO identity provider (SAML/OIDC claims) |        No       | Read-only attributes from the user's login token |

When the same key exists in both sources, the `DATABASE` value takes precedence — unless a transient (session-specific) attribute is passed at impersonation time, which overrides both for that session only.

## Setting attributes

Attributes can be set at three points in a user's lifecycle: when the user is first provisioned, updated later via API, or passed at impersonation time for session-specific context.

### At creation time

Pass `userAttributes` in `CreateUsersInput` when provisioning the user. This is the most efficient option when you know the attributes upfront:

```bash theme={null}
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
    "query": "mutation CreateUsers($input: CreateUsersInput!) { createUsers(input: $input) { status { code message } } }",
    "variables": {
      "input": {
        "emails": ["alice@yourcompany.com"],
        "workspaceID": "workspace_123",
        "roleAssignments": [{ "roleId": "00000000-0000-0000-0000-000000000003", "scopes": ["{{DOMAIN_ID}}"] }],
        "sendWelcomeEmail": true,
        "userAttributes": [
          { "key": "account_id", "value": "acct_456" },
          { "key": "region", "value": "us-east" }
        ]
      }
    }
  }' \
  https://{ACCOUNT}.wisdom.ai/graphql
```

<Note>
  Replace `{ACCOUNT}.wisdom.ai` with the base URL of your WisdomAI tenant — the same domain you use to log in. Both `wisdom.ai` and `askwisdom.ai` are valid depending on your deployment.
</Note>

### Updating later

Call `setUserAttributes` to replace the user's DATABASE-sourced attributes after they've been created:

```bash theme={null}
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
    "query": "mutation SetUserAttributes($input: SetUserAttributesInput!) { setUserAttributes(input: $input) { status { code message } } }",
    "variables": {
      "input": {
        "userId": "user_abc123",
        "userAttributes": [
          { "key": "account_id", "value": "acct_456" },
          { "key": "region", "value": "us-west" }
        ]
      }
    }
  }' \
  https://{ACCOUNT}.wisdom.ai/graphql
```

<Warning>
  `setUserAttributes` **replaces all DATABASE-sourced attributes**. Include every attribute the user should have after the call — omitting an attribute removes it.
</Warning>

### At impersonation time (transient)

Pass `attributes` in `impersonateUser` for session-only overrides. These are applied for the duration of the JWT only and are never persisted:

```bash theme={null}
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation ImpersonateUser($accessToken: String!, $userEmail: String!, $attributes: [UserAttributeInput!]) { impersonateUser(accessToken: $accessToken, userEmail: $userEmail, attributes: $attributes) }",
    "variables": {
      "accessToken": "<your_access_token>",
      "userEmail": "alice@yourcompany.com",
      "attributes": [
        { "key": "report_context", "value": "q3-summary" }
      ]
    }
  }' \
  https://{ACCOUNT}.wisdom.ai/graphql
```

Transient attributes override DATABASE-sourced values for that session. They are useful for passing request-scoped context that should not be stored on the user.

## Choosing the right approach

| Use case                                                      | Recommended approach                                                 |
| ------------------------------------------------------------- | -------------------------------------------------------------------- |
| Attributes that are stable for the user (e.g., `account_id`)  | Set at creation via `createUsers`, or update via `setUserAttributes` |
| Attributes that change per request or should not be persisted | Pass as Transient (Session) attributes in `impersonateUser`          |
| Attributes sourced from SSO claims                            | Read automatically from the JWT — no action needed                   |

## Related articles

<CardGroup>
  <Card title="Create Users" icon="user-plus" href="/integrations/graphql-api/mutations/user/create-users">
    Set attributes at provisioning time
  </Card>

  <Card title="Set User Attributes" icon="tag" href="/integrations/graphql-api/mutations/user/set-user-attributes">
    Update DATABASE-sourced attributes on existing users
  </Card>

  <Card title="Impersonate User" icon="user-secret" href="/integrations/graphql-api/mutations/auth/impersonate-user">
    Pass transient attributes at session time
  </Card>

  <Card title="List Users" icon="users" href="/integrations/graphql-api/queries/user/list-users">
    Inspect a user's current attributes and their source
  </Card>
</CardGroup>


# User Lifecycle
Source: https://docs.wisdom.ai/integrations/user-management/user-lifecycle



This guide walks through the full workflow for creating and managing users via the WisdomAI GraphQL API. User attributes are key-value pairs attached to a user that drive parameterized connection resolution, row-level authorization, and personalized data access.

**Workflow in short:**

1. Create one or more users with role assignments and (optionally) attributes
2. Update attributes on existing users as needed
3. Query users to look up IDs or verify attribute state
4. Remove users when offboarding
5. Impersonate a user to start an embedded session

## Prerequisites

* **GraphQL endpoint:** `https://{ACCOUNT}.wisdom.ai/graphql`
* **Access token:** A valid bearer token with `iam:write` permission — contact `support@askwisdom.ai` to obtain one
* **Workspace ID** (optional): Required only for multi-workspace deployments

<Note>
  Replace `{ACCOUNT}.wisdom.ai` with the base URL of your WisdomAI tenant — the same domain you use to log in. Both `wisdom.ai` and `askwisdom.ai` are valid depending on your deployment.
</Note>

## Step 1: Create users

Use [`createUsers`](/integrations/graphql-api/mutations/user/create-users) to provision one or more users by email. You can assign roles, set initial attributes, add them to user groups, and optionally send a welcome email — all in a single call.

If the user already exists, the call succeeds but **re-applies the role assignments you pass in**, overwriting any manually assigned roles. To avoid resetting roles on existing users, check [`listUsers`](/integrations/graphql-api/queries/user/list-users) first and skip `createUsers` for users already provisioned.

```bash theme={null}
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
    "query": "mutation CreateUsers($input: CreateUsersInput!) { createUsers(input: $input) { status { code message } } }",
    "variables": {
      "input": {
        "emails": ["alice@yourcompany.com"],
        "workspaceID": "workspace_123",
        "roleAssignments": [{ "roleId": "00000000-0000-0000-0000-000000000003", "scopes": ["{{DOMAIN_ID}}"] }],
        "sendWelcomeEmail": true,
        "userAttributes": [
          { "key": "account_id", "value": "acct_456" },
          { "key": "region", "value": "us-east" }
        ]
      }
    }
  }' \
  https://{ACCOUNT}.wisdom.ai/graphql
```

You can pass multiple emails in a single call. All users receive the same roles and attributes:

```bash theme={null}
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
    "query": "mutation CreateUsers($input: CreateUsersInput!) { createUsers(input: $input) { status { code message } } }",
    "variables": {
      "input": {
        "emails": ["alice@yourcompany.com", "bob@yourcompany.com", "carol@yourcompany.com"],
        "workspaceID": "workspace_123",
        "roleAssignments": [{ "roleId": "00000000-0000-0000-0000-000000000003", "scopes": ["{{DOMAIN_ID}}"] }],
        "sendWelcomeEmail": true,
        "userAttributes": [
          { "key": "account_id", "value": "acct_456" }
        ]
      }
    }
  }' \
  https://{ACCOUNT}.wisdom.ai/graphql
```

<Note>
  **Email uniqueness:** User matching is email-based. If your embedded users may share email addresses across tenants, append a unique identifier to the email prefix — for example, `alice+tenant123@yourcompany.com`. This prevents cross-tenant session collisions.
</Note>

For the full input schema, see [Create Users](/integrations/graphql-api/mutations/user/create-users).

## Step 2: Update user attributes

Use [`setUserAttributes`](/integrations/graphql-api/mutations/user/set-user-attributes) to replace the DATABASE-sourced attributes on an existing user at any time.

<Warning>
  `setUserAttributes` **replaces all DATABASE-sourced attributes**. Always include the full desired set — omitting an attribute removes it. JWT-sourced attributes (from SSO claims) are not affected.
</Warning>

```bash theme={null}
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
    "query": "mutation SetUserAttributes($input: SetUserAttributesInput!) { setUserAttributes(input: $input) { status { code message } } }",
    "variables": {
      "input": {
        "userId": "user_abc123",
        "userAttributes": [
          { "key": "account_id", "value": "acct_456" },
          { "key": "region", "value": "eu-west" },
          { "key": "property_ids", "value": "prop_1,prop_2,prop_3" }
        ]
      }
    }
  }' \
  https://{ACCOUNT}.wisdom.ai/graphql
```

## Step 3: Query users and their attributes

Use [`listUsers`](/integrations/graphql-api/queries/user/list-users) to look up user IDs or verify current attribute state.

```bash theme={null}
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
    "query": "query ListUsers($workspaceId: ID) { listUsers(workspaceId: $workspaceId) { id email name userAttributes { key value source } roleAssignments { role scopeId } } }",
    "variables": {
      "workspaceId": "workspace_123"
    }
  }' \
  https://{ACCOUNT}.wisdom.ai/graphql
```

Each attribute includes a `source` field:

| Source     | Set by                                   | Mutable via API |
| ---------- | ---------------------------------------- | :-------------: |
| `DATABASE` | `createUsers`, `setUserAttributes`       |       Yes       |
| `JWT`      | SSO identity provider (SAML/OIDC claims) |        No       |

## Step 4: Delete users from a workspace

Use [`deleteUsersFromWorkspace`](/integrations/graphql-api/mutations/user/delete-users-from-workspace) to remove one or more users from a workspace.

<Warning>
  This action is **irreversible**. Deleted users lose all role assignments, attributes, and access to the workspace. Verify the correct user IDs before calling this mutation.
</Warning>

```bash theme={null}
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
    "query": "mutation DeleteUsersFromWorkspace($input: DeleteUsersFromWorkspaceInput!) { deleteUsersFromWorkspace(input: $input) { status { code message } } }",
    "variables": {
      "input": {
        "ids": ["user_abc123", "user_def456"],
        "workspaceID": "workspace_123"
      }
    }
  }' \
  https://{ACCOUNT}.askwisdom.ai/graphql
```

## Step 5: Impersonate a user to start an embedded session

Use [`impersonateUser`](/integrations/graphql-api/mutations/auth/impersonate-user) to generate a short-lived JWT for a user. Pass this JWT as the `token` query parameter in your iframe embed URL.

This mutation is public and unauthenticated — no `Authorization` header is required. The access key is passed directly as an argument and must only be called from your server.

```bash theme={null}
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation ImpersonateUser($accessToken: String!, $userEmail: String!) { impersonateUser(accessToken: $accessToken, userEmail: $userEmail) }",
    "variables": {
      "accessToken": "<your_access_key>",
      "userEmail": "alice@yourcompany.com"
    }
  }' \
  https://{ACCOUNT}.wisdom.ai/graphql
```

To pass session-only attributes (transient overrides that are not persisted):

```bash theme={null}
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation ImpersonateUser($accessToken: String!, $userEmail: String!, $attributes: [UserAttributeInput!]) { impersonateUser(accessToken: $accessToken, userEmail: $userEmail, attributes: $attributes) }",
    "variables": {
      "accessToken": "<your_access_key>",
      "userEmail": "alice@yourcompany.com",
      "attributes": [
        { "key": "report_id", "value": "q3-sales-summary" }
      ]
    }
  }' \
  https://{ACCOUNT}.wisdom.ai/graphql
```

The response is a raw JWT string:

```json theme={null}
{
  "data": {
    "impersonateUser": "eyJhbGciOiJSUzI1NiIsInR5..."
  }
}
```

The token expires after **1 hour**. Use it in your iframe `src`:

```html theme={null}
<iframe
  src="https://{ACCOUNT}.wisdom.ai/embed/dashboards/<id>?token=<JWT>"
  style="width: 100%; height: 100%; border: 0;" />
```

WisdomAI will request a new token automatically via `postMessage` before expiry. See [Impersonate user](/integrations/graphql-api/mutations/auth/impersonate-user) for the full refresh flow.

<Tip>
  Attributes that are stable for a given user (such as `account_id`) should be set permanently via `createUsers` or `setUserAttributes`. Attributes that change per session (such as a selected view or context) can be passed transiently via `attributes` in `impersonateUser`.
</Tip>

## Related articles

<CardGroup>
  <Card title="Embedding Overview" icon="code" href="/integrations/embeddings/embedding">
    Full server-side embedding flow
  </Card>

  <Card title="Delete Users from Workspace" icon="user-minus" href="/integrations/graphql-api/mutations/user/delete-users-from-workspace">
    Remove users when offboarding
  </Card>

  <Card title="List Users" icon="users" href="/integrations/graphql-api/queries/user/list-users">
    Query users and inspect their attributes
  </Card>
</CardGroup>


# Access Management
Source: https://docs.wisdom.ai/manage-account/access-management



We use **role-based access control (RBAC)** to ensure users have the permissions they need for their jobs. In an RBAC model, each user is assigned one or more roles, and each role bundles a set of capabilities. Our tool also implements **granular access controls** (including row- and column-level security) to protect data. This ensures that team members access only the information they need to do their job.

## Core roles in WisdomAI

Every operation in WisdomAI, from viewing dashboards to managing data sources, falls under these role-based permissions:

* [Administrator](#administrator)
* [Data Administrator](#data-administrator)
* [Explorer](#explorer)
* [Observer](#observer)

### Administrator

The Administrator is the superuser of the WisdomAI platform with full system-wide privileges. Administrators are responsible for the organization's foundational setup and governance. They can:

* **Manage users and roles**: Invite or remove users, assign or modify roles, and oversee access permissions.
* **Manage Domains**: Configure and maintain organizational Domains within WisdomAI.
* **Connect and organize data**: Link external data sources, manage schemas (i.e., the structure of tables and relationships), and context import, which ingests business rules and data dictionaries.
* **Oversee your organization's content**: Review, publish, or unpublish key assets, such as dashboards and models, to control visibility and access. Edit and manage all dashboards and schedules.
* **Monitor and audit activity**: Track system usage, access logs, and platform health metrics to ensure smooth operation. View all conversations from all users in the workspace.
* **Manage integrations**: Connect Slack and configure workspace-level integrations and settings.

<Info>
  Every WisdomAI instance must have at least one Administrator.
</Info>

### Data Administrator

The Data Administrator manages and prepares data assets within specific Domains they have been assigned to. They do not have global system permissions, but can:

* **Connect Domain-level data**: Set up and configure data sources for their assigned Domains.
* **Model business context**: Define metrics, entities, and relationships relevant to their Domain.
* **Manage content**: Create and maintain Dashboards and Domain-specific assets, as well as manage access to Dashboards and Reports.
* **Apply data policies**: Set row-level and column-level access rules and validation policies. Bypass row-level security to view all underlying data when needed.
* **Manage AI agents**: Create, edit, and manage AI agents for automated data workflows within the Domain.
* **Run evaluations**: Create and run evaluation sets to assess domain quality, and view the questions log and SQL execution history.
* **Administer the Domain**: Manage recommended questions, invite users to the Domain, and access the SQL playground and system monitoring.
* **Collaborate with Explorers**: Ensure data is usable, discoverable, and tailored to user needs.

<Info>
  Data Administrators cannot manage users and roles.
</Info>

### Explorer

Explorers are data consumers. They use WisdomAI to explore, analyze, and interact with data through dashboards and chat within the Domains they have access to. They can:

* **Ask questions**: Use natural language chat to query data.
* **Use enterprise context**: Access organizational knowledge directly within the chat to ground responses in business-specific logic.
* **Work with SQL**: Execute and edit the SQL powering any chart or visualization in chat, and expand AI workstream details to inspect the reasoning behind a result.
* **Create dashboards and reports**: Build new dashboards and set up scheduled reports to share findings with the team. Can also view dashboards that have been shared with all users in the organization, or that have been shared directly with them.
* **Share insights**: Export results to Slack or email, share content with specific users, and save views for later use.

<Info>
  Explorers cannot manage data sources, users, or settings.
</Info>

### Observer

The Observer role provides "read-only" access to the platform. This role is ideal for stakeholders who need to see high-level results without interacting with the underlying data or creating new content.

* **Read-only access**: View dashboards that have been shared with all users in the organization, or that have been shared directly with them.
* **No Resource Creation**: Cannot create dashboards or data models.
* **No Chat Interaction**: Cannot use the natural language chat to query data.

## Role comparison table

| Capability                     | Administrator | Data Administrator | Explorer | Observer |
| :----------------------------- | :-----------: | :----------------: | :------: | :------: |
| **User and Role Management**   |       ✅       |          ❌         |     ❌    |     ❌    |
| **Domain Management**          |       ✅       |          ❌         |     ❌    |     ❌    |
| **Audit Logs & Usage Metrics** |       ✅       |          ❌         |     ❌    |     ❌    |
| **Data Source Management**     |       ✅       |          ✅         |     ❌    |     ❌    |
| **Domain Data Modeling**       |       ✅       |          ✅         |     ❌    |     ❌    |
| **Row/Column-Level Security**  |       ✅       |          ✅         |     ❌    |     ❌    |
| **Ask Questions (Chat)**       |       ✅       |          ✅         |     ✅    |     ❌    |
| **Create Dashboards/Reports**  |       ✅       |          ✅         |     ✅    |     ❌    |
| **View Dashboards/Reports**    |       ✅       |          ✅         |     ✅    |     ✅    |

## Next steps

<CardGroup>
  <Card title="Row Level Access Control" icon="user-shield" href="/manage-account/row-level-access-control/row-level-access-control">
    Learn how to restrict data access for specific users or roles at the row level.
  </Card>

  <Card title="Supported Data Sources" icon="database" href="/getting-started/connect-data-sources/supported-data-sources">
    Explore the full list of databases and platforms you can connect to the system.
  </Card>

  <Card title="How WisdomAI Works" icon="brain" href="/getting-started/how-wisdom-ai-works">
    Understand the core concepts and architecture behind the platform's data analysis capabilities.
  </Card>

  <Card title="Basic Tutorial: Connect and Test" icon="rocket" href="/setting-up-wisdom-ai/basic-tutorial-connect-and-test">
    Walk through the initial setup to connect a data source and run your first query.
  </Card>
</CardGroup>


# Automated Provisioning (JIT & SCIM)
Source: https://docs.wisdom.ai/manage-account/automated-provisioning



For organizations using Single Sign-On (SSO), WisdomAI can automate account creation and synchronization, eliminating the need to manually invite users.

## Just-in-time (JIT) provisioning

When SSO and JIT are enabled, user accounts are created automatically the first time they log in to the platform, removing the manual overhead of sending email invitations.

<Note>
  **Setup**: You must contact WisdomAI Support to enable JIT for your specific instance.
</Note>

## SCIM provisioning

When SSO and SCIM (System for Cross-domain Identity Management) are enabled, users are synchronized directly from your Identity Provider (IdP) down to WisdomAI.

Here's how it works:

* **Dynamic Syncing**: If a user is added in your SSO provider, Wisdom automatically creates an equivalent user.
* **Automatic Updates**: Any changes to a user profile or the removal of a user on the SSO side are immediately reflected in the Wisdom platform.
* **Group Management**: When SCIM is enabled, user group memberships are managed entirely by your IdP.

### Enable SCIM

To set up SCIM provisioning, follow these steps:

1. **Generate Setup Link**: Open the SSO setup suite and generate a secure setup link.
2. **Configure your IdP**: Share this link with your IT administrator to configure SCIM in your Identity Provider. Note that this link is valid for 7 days.
3. **Activate**: Once the IdP is configured, toggle the **Enable SCIM Provisioning** option to "on" within your Wisdom settings.

<Frame>
  <img alt="Snippet showing the sso configuration page" />
</Frame>

## Next steps

<CardGroup>
  <Card icon="database" href="/manage-account/role-mapping-and-sso-groups" title="Role Mapping & SSO Groups">
    Automate users' permission levels by mapping Identity Provider (IdP) data to WisdomAI roles.
  </Card>

  <Card icon="user-shield" href="/manage-account/row-level-access-control/row-level-access-control" title="Row-Level Access Control">
    Learn how to restrict data access for specific users or roles at the row level.
  </Card>
</CardGroup>


# Compliance and Best Practices
Source: https://docs.wisdom.ai/manage-account/compliance-and-best-practices



Our commitment to transparency and user trust is paramount. We encourage you to review our [Privacy Policy](/manage-account/privacy-policy) to understand how we collect, use, and protect your data. Additionally, our [Terms of Use](https://www.askwisdom.ai/terms-of-service) outline the legal framework governing your use of our services. By using our platform, you agree to these terms and policies.

<Info>
  If you have any questions concerning security, reach us at [security@datawisdom.ai](mailto:security@datawisdom.ai).
</Info>


# Privacy Policy
Source: https://docs.wisdom.ai/manage-account/privacy-policy

WisdomAI

Wisdom AI, Inc. ("WisdomAI", "we", "our") is committed to maintaining the privacy of its users ("user", "you"). The following information describes how WisdomAI collects and processes information about you when you use our website (the "Website") and Platform (as defined below).

Our Privacy Policy explains:

* What information we collect and why we collect it.
* How we use that information.
* Your rights with regard to the collection of such information.

By using our Website and Platform, you agree to this Privacy Policy.

WisdomAI provides a cloud based data analytics platform ("Platform") to its customers ("Customer/s") which collects data from the Customer's systems, automatically and through integrations and manual uploads, for AI based deep data insights and providing self service analytics capabilities for non-technical personnel ("Services"). The Website provides information about WisdomAI, the Platform and Services and enables its users to log in to the Platform and contact WisdomAI with respect to the Services.

## Collecting Information

Please note that the scope of this Privacy Policy is limited only to information collected by WisdomAI through your use of its Website and Platform. Some information may be automatically collected, and some is collected when you interact with our Website and Platform. Information from which you can be personally identified may be collected ("Personal Information"). The Personal Information we may collect about you includes the following:

### 1. Account information

If you wish to register to receive the Services and create an account with WisdomAI ("Account"), we will collect your Personal Information such as your full name, and email address.

### 2. Profile information

When we set your Account, you will be required to choose a username and password so we can create your user profile. We will also collect any feedback you submitted or comments posted.

### 3. Log-In to the Platform

If you wish to log-in to your Account to use the Platform via the Website, we may also use a Single Sign-On account ("SSO") such as Google or other available SSO services. Signing in via the SSO will provide us with access to information these SSO services obtain about you, and all in accordance with your specific SSO's privacy settings.

### 4. Third-Party Services Information

Typically, Third-Party Services are software services that integrate with WisdomAI Services. Each Customer can permit its authorized users ("Authorized Users") to enable and disable these integrations in accordance with the Customer's needs. WisdomAI may also develop and offer WisdomAI applications that connect the Platform with a Third-Party Service. Once enabled, the provider of a Third-Party Service may share certain information with WisdomAI. Please note that Authorized Users should check the privacy settings and notices in these Third-Party Services to understand what data may be disclosed to WisdomAI.

### 5. Contact Form

If you wish to contact us for support regarding our Services, Website, Platform, this Privacy Policy or any other matter, we will collect your name, email address, company, position and the content you submitted to facilitate your inquiry.

### 6. Live Chat

If you wish to contact one of our agents via our live chat, we will collect your name, email address, and the content you submitted to facilitate your inquiry.

### 7. Newsletter

If you wish to register to our newsletter and to be provided with information on the Services, subject to your consent, we will collect your email address, and will send you the required materials.

### 8. Interactions

WisdomAI may receive other Personal Information when submitted to our Websites or Platform or in other ways, such as if you participate in a focus group, contest, activity or event, apply for a job, enroll in an educational program hosted by WisdomAI or a vendor, request support, interact with our social media accounts or otherwise communicate with WisdomAI.

### 9. Usage Information

**Log Data**

As with most technology services delivered over the Internet, our servers automatically collect information when you access or use our Websites or Platform and record it in log files. This log data may include the Internet Protocol (IP) address, the address of the web page visited before using the Website or Platform, browser type and settings, the date and time the Platform or Website were used, information about browser configuration and plugins, language preferences and cookie data.

**Device Information**

WisdomAI collects information about devices accessing the Platform or Website, including type of device, what operating system is used, device settings, application IDs, unique device identifiers and crash data. Whether WisdomAI collects some or all of this information often depends on the type of device used and its settings.

**Location Information**

WisdomAI receives information from Authorized Users, Customers and other third parties that may help WisdomAI approximate user location. WisdomAI may, for example, use a business address submitted by a Customer, or an IP address received from the Authorized User browser or device to determine approximate location. WisdomAI may also collect location information from devices in accordance with the consent process provided by the user device.

Please note that with regard to information collected when providing our Services to Customers, any notification requirements towards employees and Authorized Users shall apply on the respective Customer, and all to the extent required under the applicable law.

## Use of Information

We use the Personal Information we collect from you for a range of different business purposes according to different legal bases of processing. We may use or process your Personal Information for the following purposes. One or more purposes may apply simultaneously.

### 1. Providing the Requested Services

We collect Personal Information of Authorized Users to enable them to operate the Platform and facilitate the Services for the Customer who authorized them to use the Platform on its behalf.

We collect the Personal Information, included in your Account and Profile to enable you to use the Platform.

We will collect your Personal Information when you contact us via the contact form or online chat to facilitate your inquiry regarding WisdomAI, the Platform, Website or Services.

We may collect the Personal Information of Customer's employees or other individuals whose Personal Information is included in the systems and files that WisdomAI is provided access to when providing its Services.

Such collection of information will enable us to provide you with the Services as well as technical and professional assistance, with regard to the Website and Platform you use or intend to use. We process the Personal Information where it is necessary for the adequate performance of the contract we have with our Customers.

### 2. Improvement and Development of the Services

We collect Personal Information to improve and develop our Services and understand feedback on WisdomAI Website and Platform and to help provide more information on the use of our Services quickly and easily.

We collect Personal Information for ongoing review and improvement of the information provided on our Website and Platform to ensure it is user friendly.

We collect Personal Information to improve the management and administration of our business and maintain compliance with our internal policies and procedures.

We conduct surveys and research, test features in development, and analyze the information we have to evaluate and improve our Website and Platform, develop new features, and conduct audits and troubleshooting activities.

We process this information in light of our legitimate interest in improving the Website and Platform, to allow our users to have the best experience.

### 3. Maintain a Safe and Secure Environment

We may use your information to detect and prevent fraud, abuse and security incidents in the following ways:

* Verify and authenticate your identity and prevent unauthorized or illegal activity;
* Enhance the safety and security of our Website and Platform;
* Conduct security investigations and risk assessments;
* Prevent or take action against activities that are, or may be, in breach of our terms of service or applicable law.

We process this information in light of our legitimate interest in improving our Website and Platform by enabling our users to browse in a secure environment.

### 4. Personalize Content, Advertising and Marketing

If you have used WisdomAI's Services in the past, we have a legitimate business interest for matching the data we collect with other data we had already collected.

This enables us to understand your needs and interests, optimize the content we send you and make it more suitable and relevant to your needs.

This also enables us to improve your experience on the Website and Platform by providing you with personalized content, recommendations, and features.

### 5. For compliance, fraud prevention, and safety

We may use your Personal Information and disclose it to law enforcement, government authorities, and private parties as we believe necessary or appropriate to:

* Protect our, your or others' rights, privacy, safety or property (including legal claims);
* Enforce the terms and conditions that govern the Service; and
* Protect, and deter against fraudulent, harmful, unauthorized, unethical or illegal activity.

We process this information for compliance with a legal obligation that we may be subject to.

### 6. With your consent

In some cases we may specifically ask for your consent to collect, use or share your Personal Information, such as when we send you our newsletter or when required by law.

## Disclosure of Information and Transfer of Data

Except as otherwise provided in this Privacy Policy, we reasonably attempt to ensure that we never intentionally disclose any of your Personal Information, to any third party without having received your permission, except as provided for herein or otherwise as permitted or required under law.

In order to perform our contractual and other legal responsibilities or purposes, we may, from time to time, need to share your Personal Information with third parties as detailed below.

**Corporate Affiliates**

We may share your Personal Information with our corporate parent, subsidiaries, and affiliates, for purposes consistent with this Privacy Policy.

**Service Providers**

We may share your Personal Information with third party companies and individuals that provide services on our behalf or help us operate the Service (such as customer support, hosting, analytics, email delivery, marketing, and database management services). These third parties may use your personal information only as directed or authorized by us and in a manner consistent with this Privacy Policy, and are prohibited from using or disclosing your information for any other purpose.

**Professional Advisors**

We may disclose your Personal Information to professional advisors, such as lawyers, bankers, auditors and insurers, where necessary in the course of the professional services that they render to us.

**For Compliance, Fraud Prevention and Safety**

We may share your Personal Information for the compliance, fraud prevention and safety purposes described above. Furthermore, information about you may also be released in order to comply with any valid legal obligation or inquiry or process such as a search warrant, subpoena, statute or court order. We will also release specific information in special cases, such as if you use the Website or the Platform to perform an unlawful act or omission or take any act or omission that may damage WisdomAI, its property and goodwill, or if there is an attempted breach of the security of the Website or Platform or a physical or property threat to you or others.

**During a change to WisdomAI's business**

If Wisdom AI, Inc. engages in a merger, acquisition, bankruptcy, dissolution, reorganization, sale of some or all of WisdomAI's assets or stock, financing, public offering of securities, acquisition of all or a portion of WisdomAI's business, a similar transaction or proceeding, or steps in contemplation of such activities, some or all Personal Information may be shared or transferred, subject to appropriate and commercially reasonable confidentiality arrangements.

The above mentioned third parties may be located in countries other than your own, and we may send them information we receive. When such third party service providers process your Personal Information on our behalf, we will assure that they comply with obligations similar to those which are set forth in this Privacy Policy. We will also assure that they will abide by our data privacy and security requirements, and will be allowed to use the Personal Information solely for the purposes we set. We will transfer your Personal Information while using appropriate and suitable safeguards, while using a variety of legal mechanisms, including contracts, to ensure your rights and protections travel with your data.

## Your Rights

In case you feel that any of your rights have been compromised, you have the right to file a complaint to the relevant supervisory authority.

You have the right at any time to request to access or modify your information. To exercise these options, please contact us at [privacy@datawisdom.ai](mailto:privacy@datawisdom.ai).

In some jurisdictions, in particular those located within the European Union (the "EU") or within the European Economic Area (the "EEA"), you may be afforded specific rights regarding your Personal Information. Subject to such eligibility, you may have the following rights to:

* Request a rectification of your Personal Information where the information we hold about you is incorrect or incomplete.
* Object to the processing of your Personal Information for direct marketing purposes.
* Object to the processing of your Personal Information where our legal basis for that processing is that such processing is necessary for our legitimate interests.
* Object to automated decision-making (including profiling) in certain circumstances.
* Request the erasure of your Personal Information in certain circumstances, such as where processing is no longer necessary for the purpose it was originally collected for, and there is no compelling reason for us to continue to process or store it.
* Receive your Personal Information, or ask us to transfer it to another organization that you have provided to us, which we process by automated means, where our processing is either based on your consent or is necessary for the performance of a contract with you.

Generally, with regard to information collected on our Website, WisdomAI is a "Data Controller". Therefore, if you wish to exercise the above mentioned rights, please contact us, and we will make our best efforts to fulfill your request.

With regard to information collected on employees or Authorized Users via the Platform and Services, WisdomAI is a "Data Processor". Therefore, if you are an employee or Authorized User and wish to exercise the above mentioned rights, please contact the relevant Customer, and we will make our best efforts to assist the Customer to fulfill your request.

## Cookies

We may use "cookies" and/or other technologies or files (collectively, "Cookies") to identify how visitors make use of our Website and Platform. This aggregated tracking information may be used to help us improve and enhance the Website and Platform experience for all of our users. In addition, Cookies are used for adjusting the Website and Platform to your personal preferences. Cookies contain information such as the pages you visited, the length of time you stayed on the Website and Platform, the location from which you accessed the Website and Platform and more. If you would prefer not to have Cookies stored on your computer, you may modify your browser settings to reject most Cookies, or manually remove Cookies that have been placed on your computer. However, by rejecting the Cookies, you may be unable to fully access the offerings on our Website and Platform. To find out more about Cookies, visit [www.allaboutcookies.org](http://www.allaboutcookies.org). For more information on WisdomAI's Cookie practices please see WisdomAI's Cookie Policy available at: [privacy@datawisdom.ai](mailto:privacy@datawisdom.ai).

## Opt In or Opt Out

You are always in control of your data, and if you choose to receive information from us, or others, you can change your mind later. If, at any time, you would like to stop receiving such information or opt out of a feature, you may notify us by writing to [privacy@datawisdom.ai](mailto:privacy@datawisdom.ai). You should be aware, however, that it is not always possible to completely remove or modify information in our databases and servers, although we will always make reasonable efforts to do so upon your request.

## Links to Other Websites

This Website and/or Platform may provide links to other websites. Please be aware that these other websites are not covered by our Privacy Policy. This Privacy Policy does not cover the information practices exercised by other providers of products or services, advertisers or other websites, companies or individuals, which are not owned or controlled by WisdomAI. We suggest that when linking to another website, you always read that website's privacy policy before volunteering any personally identifiable information.

## Data Security

Security is critical to WisdomAI's objectives, and WisdomAI takes security of data seriously and as a priority item. WisdomAI uses good industry-standards and practices to protect Personal Information from loss, misuse, and unauthorized access or disclosure. These steps take into account the sensitivity of the Personal Information WisdomAI collects, processes, and stores, and the current state of technology. Given the nature of communications and information processing technology, WisdomAI cannot guarantee that Personal Information in our care will be absolutely safe from intrusion by others during transmission through the Internet or while stored on our systems or otherwise. When you click a link to a third-party site, you will be leaving our site and WisdomAI doesn't control or endorse what is on third-party sites in any way whatsoever

## Data Retention

WisdomAI will retain Personal Information in accordance with applicable laws, regulations, and contractual agreements. Generally, WisdomAI does not retain information longer than necessary to provide its Services and for its reasonable business and lawful needs. This may include keeping Interaction Information for the period of time needed for WisdomAI to pursue legitimate business interests, conduct audits, comply with legal obligations, resolve disputes, and enforce our agreements.

When we no longer require the Personal Information we have collected from you, we will either delete or anonymize it or, if this is not possible (for example, because your Personal Information has been stored in backup archives), then we will securely store your Personal Information and isolate it from any further processing until deletion is possible.

## California Online Privacy Protection Act

CalOPPA requires commercial websites and online services to post a privacy policy. The law's reach stretches well beyond California to require any person or company in the United States (and conceivably the world) that operates websites collecting Personally Identifiable Information from California consumers, to post a conspicuous privacy policy on its website stating exactly the information being collected and those individuals or companies with whom it is being shared. See more at: [http://consumercal.org/california-online-privacy-protection-act-caloppa/#sthash.0FdRbT51.dpuf](http://consumercal.org/california-online-privacy-protection-act-caloppa/#sthash.0FdRbT51.dpuf).

According to CalOPPA, we agree to the following:

* Once this Privacy Policy is created, we will add a link to it on the first significant page after entering our Website and Platform.
* Our Privacy Policy link includes the word 'Privacy' and can easily be found on the Website and Platform.
* You can request to change your Personal Information by emailing us.

## California Privacy Rights

The California Consumer Privacy Act of 2018 ("CCPA") permits users who are California residents to request to exercise certain rights. If you are a California resident, the CCPA grants you the right to request certain information about our practices with respect to your Personal Information. In particular, you can request to receive information on the following:

* The categories and specific pieces of your Personal Information that we have collected.
* The categories of sources from which we collected your Personal Information.
* The business or commercial purposes for which we collected your Personal Information.
* The categories of third parties with which we shared your Personal Information.

You can be rest assured that we do not sell your Personal Information. If you choose to exercise your rights, we will not charge you different prices or provide different quality of our Services, unless those differences are related to your provision of your Personal Information.

## CAN SPAM Act

The CAN-SPAM Act is a Federal US law that sets the rules for commercial email, establishes requirements for commercial messages, gives recipients the right to have emails stopped from being sent to them, and spells out tough penalties for violations.

To be in accordance with CAN SPAM, we agree to the following:

* Not use false or misleading subjects or email addresses.
* Identify the commercial message sent to you as an advertisement when required.
* Include the physical address of our business or site headquarters.
* Monitor third-party email marketing services for compliance, if one is used.
* Honor opt-out/unsubscribe requests quickly.
* Allow users to unsubscribe by using the link at the bottom of each email.

If at any time you would like to unsubscribe from receiving future emails, you can email us at [privacy@datawisdom.ai](mailto:privacy@datawisdom.ai) and we will promptly remove you from ALL correspondence.

Please note that you must verify your identity and request before further action is taken. As a part of this process, government identification may be required. Moreover, you may designate an authorized agent to make a request on your behalf.

We endeavor to respond to a verifiable consumer request within 45 days of its receipt. If we require more time (up to 90 days), we will inform you of the reason and extension period in writing. Any disclosures we provide, will only cover the 12 month period preceding your verifiable request's receipt. If, for some reason, we cannot reply within such time frame, our response will include an explanation for our inability to comply. If you wish to exercise your CCPA rights, please contact us at: [privacy@datawisdom.ai](mailto:privacy@datawisdom.ai).

We will not discriminate against you for exercising any of your CCPA rights. Unless permitted by the CCPA, we will not:

* Deny you goods or services.
* Charge you different prices or rates for goods or services, including through granting discounts or other benefits, or imposing penalties.
* Provide you with a different level or quality of goods or services.
* Suggest that you may receive a different price or rate for goods or services or a different level or quality of goods or services.

## Children's Privacy

If you believe that we may have any Personal Information from or about a person under the age of 16, please contact [privacy@datawisdom.ai](mailto:privacy@datawisdom.ai).

IF YOU ARE UNDER THE AGE OF 16 YOU MAY NOT USE THE WEBSITE AND PLATFORM, UNLESS PARENTAL CONSENT IS PROVIDED.

If you believe that we may have any Personal Information from or about a person under the age of 16, please contact [privacy@datawisdom.ai](mailto:privacy@datawisdom.ai).

## Questions Regarding Our Privacy Policy

If you would like to contact us to discuss any queries or concerns about this Privacy Policy or WisdomAI's data protection practices, or if you are seeking to exercise any of your statutory rights, contact us on [privacy@datawisdom.ai](mailto:privacy@datawisdom.ai). WisdomAI will respond within a time frame that is compliant with all applicable regulations.

## Revisions and Modifications to our Privacy Policy

We reserve the right to revise, amend, or modify this Privacy Policy at any time. When changing the policy, we will update this posting accordingly. Please review this Privacy Policy often so that you will remain updated regarding our current policies.

## Governing Law and Jurisdiction

This Privacy Policy will be governed and interpreted pursuant to the laws of the State of California without giving effect to its choice of law rules. You expressly agree that the exclusive jurisdiction for any claim or action arising out of or relating to this Privacy Policy shall be to the competent courts in the State of California only, to the exclusion of any other jurisdiction.

## List of Sub-Processors

| Sub Processor    | Purpose of Processing                                                                 |
| ---------------- | ------------------------------------------------------------------------------------- |
| AWS              | Cloud infrastructure for our app and services                                         |
| AWS RDS          | DB infrastructure for our app and services                                            |
| Redshift         | Cloud warehouse                                                                       |
| Sentry           | Site analytics & Error tracking (app)                                                 |
| Google, Inc.     | Site analytics (web) and customer interactions (email) and business materials (Drive) |
| Slack            | Customer interactions                                                                 |
| Notion           | Documentation management                                                              |
| Hubspot          | Sales and marketing activities                                                        |
| AWS Cloudwatch   | Application logging and alerting                                                      |
| Descope          | SSO integration and User onboarding                                                   |
| Atlassian (Jira) | Proprietary issue tracking                                                            |

This page was updated in March 3, 2026


# Role Mapping & SSO Groups
Source: https://docs.wisdom.ai/manage-account/role-mapping-and-sso-groups



Once users are provisioned via SSO, you can automate their permission levels by mapping Identity Provider (IdP) data to WisdomAI roles.

### Role management through SCIM

When SCIM is enabled, your existing SSO groups are automatically detected and synced to Wisdom.

* **View Synced Groups**: Navigate to the **SSO Groups** list in the SSO Configuration settings to see groups like "Engineering" or "Sales" along with their sync status.

  <Frame>
    <img alt="Snippet showing the SSO Groups list" />
  </Frame>
* **Assign Roles to Groups**: Use the **Add SSO Group** button to link a synced group to a specific WisdomAI role (e.g., Explorer).

  <Frame>
    <img alt="Snippet showing the Add SSO Group modal" />
  </Frame>

<Note>
  Any user belonging to that SSO group will automatically inherit the assigned roles and domain permissions in WisdomAI.
</Note>

### Role management through claims

If you prefer not to use SCIM groups, you can configure roles based on "claims" within the IDP's JSON Web Token (JWT).

<Tip>
  Contact [WisdomAI support](/manage-account/contact-support) to enable claims-based role management for your instance.
</Tip>

**How the mapping works:**

1. When a user logs in, WisdomAI reads a specific claim from the JWT (typically named `roles` or `groups`) which contains a list of strings.
2. An **SSO Group** in WisdomAI acts as a bridge. It maps a specific **string element** from that JWT list to the assigned **WisdomAI Role**.
3. If a user’s JWT contains the string `"marketing_admin"`, and you have created an SSO Group in Wisdom that maps `"marketing_admin"` to the **Explorer** role, that user is automatically granted those permissions.

**Set it up:**

* Click the **Add Group** button.
* In the **Add SSO Group** modal that opens, enter the string element that matches your IDP claim in the **SSO Group Name** field.

  <Info>
    The claim should be a list of strings.
  </Info>
* **Role Assignments**: Select the Role (e.g., Explorer) and the corresponding Domains to be mapped to that string.
* Click **Create User Group** to finalize the mapping.

### Auto SSO group generation

To avoid manual mapping entirely, WisdomAI can auto-generate groups based on a specific string schema in your IdP claims.

<Tip>
  Contact [WisdomAI support](/manage-account/contact-support) to enable claims-based role management for your instance.
</Tip>

Each claim string must follow this schema:

`wisdom.[optional_workspace_uri].role.[optional_scope_type].[optional_scope]`

1. `wisdom.` prefix for namespace and versioning purposes
2. `optional workspace URI.` (default workspace if not given)
3. `role.` (one of administrator, data\_administrator, explorer, observer)
4. `optional scope type.` (required if scope is given)
5. `optional scope` (required if scope type is given)

**Examples of valid claim strings:**

* `wisdom.explorer`: Assigns the Explorer role on all domains in the default workspace.
* `wisdom.foo.explorer`: Assigns the Explorer role on all domains within the "foo" workspace.
* `wisdom.explorer.DOMAIN.ET_DOMAIN_foo`: Assigns the Explorer role to a specific domain in the default workspace.
* `wisdom.foo.explorer.DOMAIN.ET_DOMAIN_bar`: Assigns the Explorer role on a specific domain in the foo workspace.

## Next steps

<CardGroup>
  <Card icon="database" href="/getting-started/connect-data-sources/supported-data-sources" title="Supported Data Sources">
    Explore the full list of databases and platforms you can connect to the system.
  </Card>

  <Card icon="brain" href="/getting-started/how-wisdom-ai-works" title="How WisdomAI Works">
    Understand the core concepts and architecture behind the platform's data analysis capabilities.
  </Card>

  <Card icon="rocket" href="/setting-up-wisdom-ai/basic-tutorial-connect-and-test" title="Basic Tutorial: Connect and Test">
    Walk through the initial setup to connect a data source and run your first query.
  </Card>
</CardGroup>


# Column-Level Security (CLS)
Source: https://docs.wisdom.ai/manage-account/row-level-access-control/column-level-security-cls



This tutorial demonstrates how to protect sensitive information in your datasets while still enabling high-level analysis on the unmasked columns within a row. You will learn how to configure Column-Level Security (CLS) to mask specific values based on user attributes.

## Configure CLS

Follow these steps to configure CLS:

1. Navigate to the **Data Sources** tab in your project.
2. Select the table you wish to modify (e.g., `Account`).

<Frame>
  <img alt="cls-data-source" />
</Frame>

3. Ensure that **Show advanced options** is toggled on in the top-right corner.
4. Locate your sensitive column and click **Configure** under the **CLS Masking** column.

<Frame>
  <img alt="cls-sensitive-column" />
</Frame>

5. In the **Column-Level Security** modal, provide a SQL expression that determines how the data is displayed at query time.

<Frame>
  <img alt="cls-sql-expression" />
</Frame>

6. Click **Save**. The status badge in the CLS Masking column will now show as Active.

<Frame>
  <img alt="cls-active" />
</Frame>

<Tip>
  If you enter an incorrect value, such as a column name that doesn't exist, the system will alert you to the error and will not let you save it.
</Tip>

## Verifying the Implementation

Once active, CLS functions as a global security layer. It automatically enforces your masking logic across **WisdomAI Chat**, **Dashboards**, the **SQL Playground**, and **Data Source Previews**.

<Frame>
  <img alt="cls-chat" />
</Frame>

For unauthorized users, protected data will appear as hashed values. It is important to remember that CLS is applied strictly at the column level.

<Warning>
  **Avoid Data Leakage**: If you protect a column (e.g., `Customer Name`) but leave a correlative column unprotected (e.g., `Customer Email`), an unauthorized user will see the hashed name, but the clear-text email address. Ensure you apply masking to all columns that could potentially identify the sensitive entity.
</Warning>

## Next Steps

<CardGroup>
  <Card title="Users Management" icon="users" href="/manage-account/users-management">
    Manage user roles, permissions, and access to the platform.
  </Card>

  <Card title="Basic Tutorial: Connect and Test" icon="rocket" href="/setting-up-wisdom-ai/basic-tutorial-connect-and-test">
    Walk through the initial setup to connect a data source and run your first query.
  </Card>
</CardGroup>


# How to Configure Row-Level Security
Source: https://docs.wisdom.ai/manage-account/row-level-access-control/row-level-access-control



This guide walks you through how to configure Row-Level Security (RLS) filters in WisdomAI to control which rows of data users can access. You’ll learn how to set up filters using natural language or SQL, preview results, and manage RLS settings after configuration.

If you are new to RLS, start with the conceptual guide:  [**Understanding Row-Level Security**](/manage-account/row-level-access-control/understanding-row-level-security).

## Prerequisites

Before configuring RLS, make sure you have the following:

* **Admin Access:** You must have administrator privileges for your WisdomAI domain.
* **A Target Table:** Identify the table you wish to secure and understand its schema.
* **(Optional) Dynamic Filtering Setup:** For dynamic RLS, you should have one of the following configured:
  * **User Attributes:** Key-value pairs assigned to users that define their permissions (e.g., `tenantId: 'abc-123'`). Attributes can be set manually by an admin or provisioned automatically via SAML SSO.
  * **Entitlements Table:** A dedicated table that maps users to the specific data resources they are allowed to access.

## Configure RLS on a table

Once your setup is ready, follow these steps to configure row-level security for a table in your WisdomAI domain.

1. In your WisdomAI domain, navigate to **Data** > **Tables**.
2. Locate the table you want to secure, click the three-dot menu on the right side of the table row and select **Row-Level Security**. The **Row-Level Security Configuration** window will open.

<img alt="row-level-security-10-25.png" />

<Note>
  RLS filters are defined as `WHERE` clauses that WisdomAI applies to every query on the table. You can define this filter using natural language (recommended) or by writing SQL directly.
</Note>

3. Use the **Describe Filters** text box to explain your access rule in plain language.
4. Click **Generate**. WisdomAI will automatically generate a valid SQL `WHERE` clause based on your description, recognizing table columns, user attributes, and entitlements. Here are some examples to help you describe a filter:

| You Type                                                       | WisdomAI Generates                      |
| -------------------------------------------------------------- | --------------------------------------- |
| `Filter the email column by the current user's email`          | `email = USER_EMAIL()`                  |
| `Match the tenantId column with the user's tenantId attribute` | `tenantId = USER_ATTRIBUTE('tenantId')` |
| `Use the entitlements table to filter the territory name`      | SQL subquery (see below)                |

```
EXISTS (
  SELECT 1
  FROM entitlements
  WHERE user_email = USER_EMAIL()
  AND resource_type = 'Territory'
  AND (resource_value = '*' OR resource_value = territory.name)
)
```

<Info>
  For complex or highly specific rules, you can write the `WHERE` clause directly in the **SQL** text box in a valid SQL syntax. For this, you can use WisdomAI's built-in functions for dynamic filtering.

  For a complete list of functions, see [Dynamic Filters with Custom Functions](/manage-account/row-level-access-control/understanding-row-level-security#dynamic-filters-with-custom-functions).
</Info>

<img alt="row-level-security-10-25-02.png" />

5. Click **Preview**.
6. In the **Preview Table with Row-Level Security** window that opens, locate the **Impersonate User** field and enter a user's email address.
7. Click **Impersonate**. The data preview will update to show exactly what that user would see.
8. (Optional) Add temporary user attributes to test different scenarios.
9. Repeat with different users to validate all access cases.

<img alt="row-level-security-10-25-03.png" />

10. Once you have verified that the filter works correctly, close the **Preview Table with Row-Level Security** window and click **Save** to apply the RLS rule. The filter is now active and will be automatically appended to all queries against this table for non-admin users.

## Managing RLS

* **To Disable RLS:** Open the RLS configuration, clear the contents of the **SQL** text box, and click **Save**.
* **Applying RLS to Admin Users:** By default, admins can see all data. To apply RLS filters to admins as well, enable the corresponding setting in your domain's **Settings** > **Advanced** tab.
* **Using a Table as an Entitlements Source:** If the table you are securing is itself an entitlements table, check the **Set as entitlements table** option. This optimizes how WisdomAI uses it for RLS checks on other tables.

## Next steps

<CardGroup>
  <Card title="Users Management" icon="users" href="/manage-account/users-management">
    Manage user roles, permissions, and access to the platform.
  </Card>

  <Card title="Supported Data Sources" icon="database" href="/getting-started/connect-data-sources/supported-data-sources">
    Explore the full list of databases and platforms you can connect to the system.
  </Card>

  <Card title="How WisdomAI Works" icon="brain" href="/getting-started/how-wisdom-ai-works">
    Understand the core concepts and architecture behind the platform's data analysis capabilities.
  </Card>

  <Card title="Basic Tutorial: Connect and Test" icon="rocket" href="/setting-up-wisdom-ai/basic-tutorial-connect-and-test">
    Walk through the initial setup to connect a data source and run your first query.
  </Card>
</CardGroup>


# Understanding Row-Level Security
Source: https://docs.wisdom.ai/manage-account/row-level-access-control/understanding-row-level-security



Row-Level Security (RLS) is a data security feature that filters data seamlessly at the row level, ensuring users can only see the data they are permitted to access.\
Unlike table-level permissions, RLS allows for granular control based on user-specific attributes.

## Basic mechanism

The basic mechanism of RLS involves defining a per-table SQL `WHERE` clause that Wisdom automatically injects into every query that uses that table. This filter can leverage Wisdom-specific custom functions to access information about the user running the query. For example, a policy can be set only to return rows where the `user_email` column matches the logged-in user's email address.

## How the SQL executor works

All SQL queries in Wisdom pass through a central **SQL Executor** module. When a query is initiated, the SQL Executor:

1. Identifies the tables referenced in the query.
2. Looks up any RLS policies defined for those tables.
3. Resolves Wisdom custom functions (such as `USER_EMAIL()`) into their current values.
4. Rewrites the query to include the appropriate row filters safely.

This approach ensures that RLS rules are applied consistently, regardless of how the data is accessed.

## Key concepts

Understanding the core building blocks of RLS helps in configuring and managing it effectively.

### Dynamic filters with custom functions

Dynamic filters adapt to the identity of the logged-in user. Policies often rely on Wisdom's built-in functions to inject the right conditions at query time.

Commonly used functions include:

* `USER_EMAIL()` – returns the email address of the current user.
* `USER_ATTRIBUTE('attribute_name')` – retrieves a custom attribute value for the user, typically synced from a SAML SSO provider during setup.

Example:

```sql theme={null}
tenant_id = USER_ATTRIBUTE('tenantId')
```

Variants for other data types include:

* `USER_ATTRIBUTE_INT('attribute_name')` – resolves to an integer.
* `USER_ATTRIBUTE_STR('attribute_name')` – equivalent to `USER_ATTRIBUTE()` for strings.
* `USER_ATTRIBUTE_STR_LIST('attribute_name')` – maps to a list of strings, for example:

```sql theme={null}
territory_id IN USER_ATTRIBUTE_STR_LIST('territoryIds')
```

* `USER_ATTRIBUTE_INT_LIST('attribute_name')` – maps to a list of integers.

These functions let you define flexible, user-aware conditions without hard-coding values.

### Entitlements tables

For more advanced setups, RLS can leverage an entitlements table stored in your data warehouse. This table centralizes user permissions and typically includes columns like:

* `user_email`
* `resource_type`
* `resource_value`

Here's an example of an entitlements table:

| user\_email                                   | resource\_type | resource\_value |
| --------------------------------------------- | -------------- | --------------- |
| [john@askwisdom.ai](mailto:john@askwisdom.ai) | Territory      | USA             |
| [john@askwisdom.ai](mailto:john@askwisdom.ai) | Department     | \*              |

The `*` wildcard in `resource_value` grants a user access to all resources of that type.

### User attributes

User attributes, mapped from SAML attributes during SSO configuration, allow policies to reflect organizational properties such as department, region, or tenant.

## Validation and administration

Proper validation and administration ensure your RLS policies work as intended.

### Preview and impersonation

For testing purposes, you can preview filtered data:

* Impersonate a user to see the data as they would.
* Set temporary custom attributes at preview time for troubleshooting.

### Admin access control

By default, administrators bypass RLS filters. To apply the same restrictions to them, go to the **Advanced** tab in the domain's settings and enable **Enable RLS for admin**.

## Next steps

<CardGroup>
  <Card title="How to Configure Row-Level Security" icon="user-shield" href="/manage-account/row-level-access-control/row-level-access-control">
    Learn to restrict data access for specific users or roles at the row level.
  </Card>

  <Card title="User Management" icon="users" href="/manage-account/users-management">
    Manage user roles, permissions, and access to the platform.
  </Card>
</CardGroup>


# Manual User Management
Source: https://docs.wisdom.ai/manage-account/users-management



When Single Sign-On (SSO) is not enabled for your organization, users are managed manually through the **Users IAM page**. This article guides Administrators on how to invite users and assign permissions based on responsibilities.

## Invite users

As an administrator, you can invite new users to join your WisdomAI environment via email.

1. Navigate to **Users** > **Invite Users**. The Invite Users modal window will open.

<Frame>
  <img alt="Image showing the Users interface" />
</Frame>

2. Enter the **email address** of the person you want to invite.
3. Assign the appropriate **role** and the corresponding **Domain**.
   * You can assign more than one Role and Domain to a user.
   * To delete any record, click on the bin icon.
4. Click **Invite**.

<Warning>
  Assign roles carefully based on user responsibilities. Role-based access control ensures users only access the data and features they need.
</Warning>

<Frame>
  <img alt="Image showing the Invite Users Modal" />
</Frame>

## Assign roles (individual)

Roles may be managed on a per-user basis. Whether you need to add or change a user's role, you can do it from the users list.

1. Navigate to **Users** > Find the user to assign/change the role, click on the kebab menu (three vertical dots) on its row, and select **Edit**. The Edit User modal window will open.

<Frame>
  <img alt="Image showing the Edit Option" />
</Frame>

2. **Edit** the Role/Domains information or **assign an additional Role**.
   * You may also view **Remote Attributes** synced from a provider or add **Local Attributes** for the user.
3. Click **Update**.

<Frame>
  <img alt="Image showing the Edit Users Modal" />
</Frame>

## Manage user groups

You can also create groups with roles to streamline management. Users will inherit any roles from the groups they belong to.

1. Navigate to **Users > Groups** and click **Add Group**.
2. In the **Add User Group** modal that opens, provide a name for the group (e.g., `example_group`).
3. Assign the **Role(s)** and **Domain(s)** that all group members should have.
4. Click **Create**.

   <Frame>
     <img alt="Add User Group modal" />
   </Frame>
5. Assign users to these groups via the **Edit User** modal. When a user is in a group, their profile will show roles as **Inherited from group**.

## Next steps

<CardGroup>
  <Card icon="key" href="/manage-account/automated-provisioning" title="Automated Provisioning (JIT & SCIM)">
    Use Single Sign-On (SSO) to automate user account creation and synchronization.
  </Card>

  <Card icon="database" href="/manage-account/role-mapping-and-sso-groups" title="Role Mapping & SSO Groups">
    Automate users' permission levels by mapping Identity Provider (IdP) data to WisdomAI roles.
  </Card>

  <Card icon="user-shield" href="/manage-account/row-level-access-control/row-level-access-control" title="Row-Level Access Control">
    Learn how to restrict data access for specific users or roles at the row level.
  </Card>
</CardGroup>


# Context Builder - File uploads
Source: https://docs.wisdom.ai/product-updates/february-2026/context-builder-file-uploads



Context Builder is a feature within WisdomAI's Adaptive Context Engine (wACE) that helps you build your Domain's context by using existing documentation. By uploading files like dbt YAML, internal docs, PDFs, or query logs, Context Builder proposes reviewable suggestions tailored to your data. You stay in control by accepting, rejecting, or editing suggestions before anything is published.

This guide will walk you through the steps to upload your files, extract metadata, and review the resulting suggestions.

## How it works

The process follows three stages to ensure all metadata is verified before it is added to your Domain.

<Steps>
  <Step title="Upload" icon="upload">
    Upload files directly from your **Domain** page. You can optionally provide a short prompt to steer what the system should focus on during the context extraction.
  </Step>

  <Step title="Extract" icon="wand-magic-sparkles">
    WisdomAI analyzes the content and proposes structured items like descriptions, metrics, joins, and business context. When possible, WisdomAI validates these suggestions, for example, by utilizing a test SQL execution.
  </Step>

  <Step title="Review and Publish" icon="check-double">
    Review all proposed changes in the **Suggestions** experience. Compare the suggestion side-by-side with the source file to ensure accuracy. You can choose to **Accept**, **Reject**, or **Edit** any item before publishing it to your knowledge base.
  </Step>
</Steps>

<video />

<Note>
  This feature reduces manual entry and helps standardize definitions across teams while keeping you in control through a review-first workflow. It also improves trust with source attribution by showing exactly which part of your documentation generated a suggestion.
</Note>

## Extracted metadata types

Context Builder identifies the following categories of information:

| Item Type        | Description                                       |
| :--------------- | :------------------------------------------------ |
| Descriptions     | Table and column definitions.                     |
| Metrics          | Metric definitions and associated SQL.            |
| Joins            | Relationships and join logic between tables.      |
| Business Context | Rules, definitions, conventions, and SQL hints.   |
| Reviewed Queries | Example question-to-SQL pairs for model training. |

## Supported file types

The following file types are supported when uploading files to Context Builder:

| Category           | Extensions                                        |
| :----------------- | :------------------------------------------------ |
| Text & documents   | `.txt`, `.md`, `.pdf`, `.doc`, `.docx`, `.rtf`    |
| Data & query files | `.sql`, `.json`, `.csv`                           |
| Configuration      | `.yml`, `.yaml`                                   |
| Looker             | `.lkml`, `.lookml`                                |
| Power BI           | `.pbix`, `.pbit`                                  |
| Tableau            | `.twb`, `.twbx`, `.tds`, `.tdsx`, `.tfl`, `.tflx` |

<Info>
  Excel files (`.xlsx`) are not directly supported. To include spreadsheet data, export each tab as a separate `.csv` file before uploading.
</Info>

## Target users

Context Builder is available to **Admins** and **Data Admins** who manage and curate trusted domain knowledge: descriptions, metrics, joins, and definitions.

## FAQs

<AccordionGroup>
  <Accordion title="Does anything get published automatically?">
    No. Extracted items remain as suggestions until an admin clicks **Accept** in the Suggestions experience.
  </Accordion>

  <Accordion title="Where do I review suggestions?">
    Suggestions are located in the **Context** tab of your Domain. Each entry shows the specific source content used for the extraction.
  </Accordion>

  <Accordion title="Can I guide the extraction?">
    Yes. During the upload step, you can use the prompt field to tell Wisdom exactly what metadata to look for.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="Advanced Data Modeling" icon="sitemap" href="/setting-up-wisdom-ai/advanced-data-modeling-creating-context">
    Learn how to manually create relationships and context.
  </Card>

  <Card title="Understand Domains" icon="layer-group" href="/setting-up-wisdom-ai/manage-domains/understand-domains">
    Explore how to organize your data logic using Domains.
  </Card>
</CardGroup>


# Data Query on Slack
Source: https://docs.wisdom.ai/product-updates/february-2026/data-query-on-slack



Slack in Channels allows you to `@mention` `@WisdomAI` in public or private Slack channels to ask data questions collaboratively. Previously, the Slack app only worked in direct messages. Now teams can have shared data conversations that are visible to all channel members.

This feature turns Slack into a shared space for data-driven conversations where insights are shared openly. This guide will walk you through the steps to set the data context, ask questions in a channel, and collaborate using threads.

## How it works

The process follows three steps to move data conversations from private messages to shared team spaces.

<Steps>
  <Step icon="link" title="Set the Context">
    An administrator links a specific Slack channel to a data area. This ensures that the system knows which data to reference when members ask questions within that channel.

    <Frame>
      <img alt="Connect To Slack" />
    </Frame>
  </Step>

  <Step icon="messages-question" title="Ask in the Channel">
    Any member of the channel can type a question and @mention **@WisdomAI**. The system processes the natural language request based on the linked data context.
  </Step>

  <Step icon="comments" title="Collaborate in Threads">
    Responses appear as threaded replies. This keeps the main channel history clean while allowing team members to ask follow-up questions or discuss the results in a preserved context.

    <Frame>
      <img alt="Query Slack Thread" />
    </Frame>
  </Step>
</Steps>

## Key capabilities

Data Query on Slack helps teams integrate data into their existing communication workflows:

* **Shared Visibility:** Move important data questions out of private DMs and into open channels where the whole team can learn.
* **Reduced Repetition:** Keep answers visible so teammates can see previously asked questions and results.
* **Organized Discussions:** Use Slack threads to manage detailed data conversations without cluttering the main chat.
* **Customized Contexts:** Link different Slack channels to different data areas depending on the needs of the specific team or project.

## Designed for

Querying data on Slack channels is key for:

* **Collaborative Teams** who communicate and make decisions within Slack on a daily basis.
* **Managers** who require centralized, transparent access to key metrics for better team alignment.
* **Executives** who need immediate, data-driven insights directly within high-level leadership channels.
* **Admins** who prioritize security through well-defined permission boundaries and rigorous access control.

## FAQs

<AccordionGroup>
  <Accordion title="Who can see the answers?">
    Anyone who is a member of the Slack channel can see the conversation, provided they have the necessary permissions to access the underlying data source.
  </Accordion>

  <Accordion title="Are permissions respected?">
    Yes. The system enforces access controls, ensuring each person only sees data they are authorized to access.
  </Accordion>

  <Accordion title="Can multiple channels use different data?">
    Yes. You can link each individual Slack channel to its own unique data context.
  </Accordion>

  <Accordion title="Will this clutter my channels?">
    No. All responses are neatly organized in threads to maintain readability in the main channel view.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card icon="slack" href="/integrations/connect-to-slack" title="Slack Integration Setup">
    Learn how to connect your Slack workspace to WisdomAI.
  </Card>

  <Card icon="message-question" href="/using-wisdom-ai-everyday/ask-better-questions" title="Ask Better Questions">
    Review strategies for phrasing questions to get the best results in Slack.
  </Card>
</CardGroup>


# Dual-Axis Charts
Source: https://docs.wisdom.ai/product-updates/february-2026/dual-axis-charts



Dual-Axis Charts, also known as combo charts, are visualizations that combine multiple chart types or Y-axes into a single view. They allow you to display measures with different scales or units, such as absolute revenue alongside a percentage margin, by rendering each measure as a different series type.

This feature ensures that metrics with different semantic meanings remain readable and helps you identify relationships among data points that a single axis might obscure. This guide explains how the system detects when a dual-axis chart is needed and how these charts are structured.

## How it works

The system uses specific detection methods and structural components to build these rich visualizations.

### Detection methods

The system identifies the need for a dual-axis chart in two ways:

* **Rule-based:** It recognizes keywords such as "combo chart," "dual axis," or "dual-axis" in your query.
* **LLM-based:** The AI automatically detects when requested measures use different scales or have different semantic meanings.

### Chart structure

Each dual-axis chart is built using a specific layout specification:

* **Dual Y-axes:** Independent scales are provided for both the left and right Y-axes.

<Frame>
  <img alt="Dual Axis Chart" />
</Frame>

* **Multiple Series Types:** Each measure can be rendered as a **COLUMN** (vertical), **BAR** (horizontal), **LINE**, or **AREA**.
* **Layout Mapping:** The system explicitly defines what data appears on the X-axis, which measures belong to each Y-axis, and the rendering position for each series. The chart structure is defined using **ChartLayoutSpec**, which includes:
  * **x\_axis.columns\[]** - What goes on the X-axis
  * **y\_axes\[].columns\[]** - Measures per Y-axis
  * **y\_axes\[].series\_type** - How to render (column/line/bar/area)
  * **y\_axes\[].position** - Left or right axis
  * **series\_dimension** - Dimension for colored series grouping

## Key capabilities

Dual-Axis Charts allow you to perform advanced analysis within a single visualization:

* **Compare Different Scales:** View metrics with entirely different units, like transaction volume and conversion rates, in one place.
* **Mix Visual Styles:** Combine bars and lines to distinguish between volume-based data and efficiency-based trends.
* **Consolidate Insights:** Replace multiple standalone charts with a single visual that tells a more complete story.

## Common use cases

| Metric A (Bars/Area) | Metric B (Line) | Purpose                                                  |
| :------------------- | :-------------- | :------------------------------------------------------- |
| Revenue              | Margin %        | Compare absolute profit to efficiency.                   |
| Transaction Volume   | Conversion Rate | Track activity alongside success rates.                  |
| Pipeline Size        | Win Rate        | Monitor potential revenue against closing effectiveness. |
| Spend                | ROI             | Visualize investment against return levels.              |

## Targeted users

This feature is available to **Explorers** and **Admins**.

## FAQs

<AccordionGroup>
  <Accordion title="Do I need to configure axes manually?">
    No. The system automatically chooses the appropriate axes and chart types based on the detected metrics.
  </Accordion>

  <Accordion title="Can I mix different chart styles?">
    Yes. Combo charts can combine bars, lines, or area series within a single visualization.
  </Accordion>

  <Accordion title="When should I use a combo chart?">
    Use a combo chart when you need to compare metrics on different scales or when you want to see how two distinct trends relate.
  </Accordion>

  <Accordion title="Will this work with time series data?">
    Yes. Dual-axis charts are particularly effective for making time-based comparisons across multiple metrics.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card icon="chart-mixed" href="/advanced-features/visualization-types-and-properties" title="Visualization Types">
    Explore the full library of chart types and properties available in WisdomAI.
  </Card>

  <Card icon="flask" href="/product-updates/february-2026/knowledge-playground" title="Knowledge Playground">
    Experiment with different queries to see how the system generates dual-axis charts.
  </Card>
</CardGroup>


# Changelog
Source: https://docs.wisdom.ai/product-updates/february-2026/february-changelog



<Update label="Updates">
  ### 🧠 Smarter Data Crawling

  WisdomAI has improved its warehouse data crawling to populate filter dropdowns, autocomplete suggestions, and data exploration features by identifying columns that contain meaningful categorical values and prioritizing them during scheduled runs. Other columns are fetched on demand, reducing unnecessary queries and improving performance for large schemas.

  **⚙️ How it works:**

  * Scheduled crawls scan selected columns with named entities (customer names, status values)
  * Adding a filter or enabling "lookup" triggers a targeted crawl for that column
  * Values appear shortly after the crawl completes

  <Accordion title="FAQs">
    <AccordionGroup>
      <Accordion title="What if a filter dropdown shows no values?">
        When you add a new filter, the dropdown may initially be empty. Within 3-4 minutes, the on-demand crawl will complete, and values will appear. Reload the page to see them.
      </Accordion>

      <Accordion title="Can I force a column to always be crawled?">
        Yes. In your domain's column settings, you can manually enable value crawling for any column. Manual settings take the highest priority and are never overridden by automatic detection.
      </Accordion>
    </AccordionGroup>
  </Accordion>

  ### 🧩 Partition & View Awareness

  WisdomAI now detects partition columns and distinguishes between base tables, views, and materialized views during schema crawling. This information is used to generate more efficient SQL queries with appropriate partition filters and optimized query strategies. This results in fewer query failures, faster performance on large datasets, and reduced warehouse costs.

  <Note>
    **Supported warehouses**: BigQuery, ClickHouse, Databricks, and Redshift.
  </Note>

  **⚙️ How it works:**

  1. Schema crawl identifies partition columns and table types
  2. Generated SQL includes partition filters to avoid full-table scans
  3. Query strategy adapts based on whether the table is a base table, view, or materialized view
  4. Background crawling prioritizes recent partitions to improve efficiency

  <Accordion title="FAQs">
    <AccordionGroup>
      <Accordion title="Do I need to configure anything?">
        No. Partition and view awareness are enabled automatically. WisdomAI detects everything during its regular schema crawl.
      </Accordion>

      <Accordion title="How does this reduce BigQuery costs?">
        BigQuery bills based on bytes scanned and will reject queries that are missing partition filters. WisdomAI handles this automatically by adding the correct filters, avoiding failed queries and costly full-table scans.
      </Accordion>
    </AccordionGroup>
  </Accordion>

  ### 🔌 Teradata Connector

  WisdomAI now connects natively to Teradata Vantage, enabling natural-language querying, AI-powered analytics, and interactive dashboards without requiring data replication. It automatically discovers schemas across databases and generates Teradata-specific SQL, while executing all queries in read-only mode to ensure data safety and compliance.

  **⚙️ How it works:**

  1. Access **Connections** > **Add connection** and select **Teradata**
  2. Enter credentials and validate access
  3. Optionally limit access using database filters
  4. WisdomAI crawls the schema and enables querying

  <Frame>
    <img alt="Teradata" />
  </Frame>

  <Accordion title="FAQs">
    <AccordionGroup>
      <Accordion title="Which Teradata products are supported?">
        WisdomAI connects to Teradata Vantage, supporting both on-premises and cloud (VantageCloud) deployments. The only requirement is that your host is network-accessible from WisdomAI.
      </Accordion>

      <Accordion title="Can WisdomAI modify data in Teradata?">
        No. WisdomAI operates in read-only mode and never writes, updates, or deletes data in your Teradata warehouse.
      </Accordion>
    </AccordionGroup>
  </Accordion>

  ### ☁️ Google Cloud Spanner Support

  WisdomAI connects directly to Google Cloud Spanner, automatically detecting whether your database uses Google Standard SQL or PostgreSQL and handling both without additional configuration. It also performs full schema discovery and executes all queries in read-only mode for safety.

  **⚙️ How it works:**

  1. Access **Connections** > **Add connection** and select **Google Cloud Spanner**
  2. Provide project details and Service Account credentials
  3. WisdomAI validates access, detects the SQL dialect, and crawls the schema

  <Frame>
    <img alt="Spanner" />
  </Frame>

  <Accordion title="FAQs">
    <AccordionGroup>
      <Accordion title="How does WisdomAI detect my Spanner SQL dialect?">
        WisdomAI automatically detects the dialect when you create the connection by querying the Spanner Admin API — no manual configuration needed.
      </Accordion>

      <Accordion title="Can WisdomAI modify data in Spanner?">
        No. WisdomAI operates in read-only mode and executes all queries as read-only snapshots, ensuring your data is never modified.
      </Accordion>
    </AccordionGroup>
  </Accordion>

  ### 🔗 AI-Powered Join Suggestions

  WisdomAI analyzes your schema to detect missing relationships between tables and validates them against actual data to ensure meaningful joins. These are surfaced as one-click suggestions that can be reviewed and applied to improve query accuracy.

  **⚙️ How it works:**

  1. WisdomAI analyzes table schemas to identify potential foreign key relationships
  2. Candidate joins are validated using real data overlap
  3. Suggestions appear in the domain for review
  4. Accept or decline each join and define the relationship type

  <Tip>
    Join suggestions are also automatically populated from Looker and Tableau imports.
  </Tip>

  <Frame>
    <img alt="Suggestions" />
  </Frame>

  <Accordion title="FAQs">
    <AccordionGroup>
      <Accordion title="How does WisdomAI know which joins to suggest?">
        WisdomAI uses an LLM to identify columns that are likely foreign keys, then validates each candidate against your actual warehouse data by checking for value overlap between columns.
      </Accordion>

      <Accordion title="Why does this matter for query accuracy?">
        Table relationships are essential for correct SQL generation. In internal testing, adding the right joins improved multi-table query accuracy from 30% to 86.7%.
      </Accordion>
    </AccordionGroup>
  </Accordion>

  ### 🔔 Notify when Completed

  WisdomAI can now notify you when long-running queries finish, even if you switch tabs. After a few seconds, you can opt in to receive a browser alert, sound, and tab update when results are ready.

  **⚙️ How it works:**

  1. After a few seconds, a **"Notify me when complete"** prompt appears
  2. Click it and grant browser notification permission if prompted
  3. Switch to any other tab or app and keep working
  4. When the response is ready, you'll receive a browser notification, an audio chime, and a tab title update simultaneously

  <Accordion title="FAQs">
    <AccordionGroup>
      <Accordion title="Do I need to install anything?">
        No. Notifications use your browser's native notification system. The first time you opt in, your browser will ask for permission, and once granted, it works automatically going forward.
      </Accordion>

      <Accordion title="What if my browser blocks notifications?">
        A message will appear in the prompt indicating notifications are blocked. You can re-enable them in your browser's site permissions settings.
      </Accordion>

      <Accordion title="Will I be notified if I close the tab?">
        Not currently. The tab must remain open, even in the background, for notifications to fire.
      </Accordion>
    </AccordionGroup>
  </Accordion>

  ### 🌍 World Map Visualization

  WisdomAI includes a choropleth world map visualization for country-level data, automatically detecting geographic dimensions and using color gradients to highlight differences in metric values. Tooltips provide exact figures for each country. Supports both country names and ISO country codes, and is available in chat and dashboards.

  **⚙️ How it works:**

  1. Queries with country-level data automatically trigger a world map visualization suggestion
  2. Countries are colored based on metric values (darker = higher)
  3. Hovering over a country displays its name and exact metric value

  <Frame>
    <img alt="World Map Visualization" />
  </Frame>

  <Accordion title="FAQs">
    <AccordionGroup>
      <Accordion title="What data does my query need to produce a world map?">
        Your data must include a column with country names or ISO country codes, and at least one numeric metric. WisdomAI will detect the country column and automatically suggest the world map.
      </Accordion>

      <Accordion title="Can I add a world map to a dashboard?">
        Yes. World map visualizations can be pinned to any dashboard, just like other chart types.
      </Accordion>
    </AccordionGroup>
  </Accordion>
</Update>

<Update label="January 2026">
  ### 💬 Slack Link Previews

  Sharing a WisdomAI link in Slack now generates a rich preview that displays charts or data tables directly in the conversation, with no clicks or context-switching required.

  **⚙️ How it works:**

  1. Paste a WisdomAI link in any Slack channel or DM
  2. Slack requests a preview from WisdomAI in the background
  3. WisdomAI verifies the poster's identity and data access
  4. A rich preview appears inline below the message

  <Accordion title="FAQs">
    <AccordionGroup>
      <Accordion title="Do I need to do anything to enable this?">
        Yes. Your organization needs to reinstall the WisdomAI app in Slack, as updated permissions are required for previews to work.
      </Accordion>

      <Accordion title="Will everyone in the channel see the preview?">
        Yes. WisdomAI checks the permissions of the user who shared the link. If they have access to the data, the preview is visible to everyone in the channel.
      </Accordion>
    </AccordionGroup>
  </Accordion>
</Update>


# Features
Source: https://docs.wisdom.ai/product-updates/february-2026/february-features



Explore the latest features and platform enhancements in WisdomAI's **February 2026** launch, focused on accelerating your development and bringing AI-powered insights directly to where your team works.

<CardGroup>
  <Card title="Context Builder - File uploads" icon="wand-magic-sparkles" href="/product-updates/february-2026/context-builder-file-uploads">
    Transform existing documentation into standardized metrics and joins in minutes.
  </Card>

  <Card title="Slack in Channels" icon="slack" href="/product-updates/february-2026/data-query-on-slack">
    Ask data questions and trigger workflows directly within Slack.
  </Card>

  <Card title="Knowledge Playground" icon="code" href="/product-updates/february-2026/knowledge-playground">
    Explore, iterate, and test knowledge-driven responses.
  </Card>

  <Card title="Ghost Text Completion" icon="keyboard" href="/product-updates/february-2026/ghost-text-completion">
    Inline suggestions appear as you type your queries.
  </Card>

  <Card title="MCP Reviewed Queries" icon="thumbs-up" href="/product-updates/february-2026/mcp-reviewed-queries">
    Improve the accuracy of tool-based answers by turning approved visualizations into learning examples for the system.
  </Card>

  <Card title="Dual-Axis Charts" icon="chart-mixed" href="/product-updates/february-2026/dual-axis-charts">
    Visualize metrics with different scales or units by combining multiple chart types and independent Y-axes into a single, cohesive view.
  </Card>
</CardGroup>

<Card title="Search the Web" icon="globe" href="/getting-started/connect-data-sources/search-the-web">
  Supplement your database analysis with real-time internet content, including industry benchmarks, market trends, and competitor data, to enrich your insights.
</Card>


# Ghost Text Completion
Source: https://docs.wisdom.ai/product-updates/february-2026/ghost-text-completion



Ghost Text Completion is an AI-powered autocomplete feature that provides real-time suggestions as you type in the chat input box. Similar to modern coding tools like GitHub Copilot or Cursor's autocomplete, it displays suggestions as gray "ghost" text that you can quickly accept or ignore.

This feature helps you write precise questions faster and discover available metrics or terms within your specific Domain. This guide will walk you through the steps to use these suggestions and how they integrate into your workflow.

## How it works

The process is designed to be seamless and keyboard-friendly, ensuring you stay in your creative flow.

<Steps>
  <Step icon="keyboard" title="Start Typing">
    Begin entering your question or command in the chat input box. The system begins analyzing your input immediately to predict the most relevant completion.
  </Step>

  <Step icon="wand-magic-sparkles" title="See Suggestions Appear">
    Helpful completions appear automatically as gray ghost text. These suggestions are tailored to the specific data, metrics, and terminology defined within your current Domain.
  </Step>

  <Step icon="check" title="Accept or Ignore">
    If the suggestion matches your intent, press **Tab** to accept it and instantly fill the text. If the suggestion is not what you need, simply continue typing to dismiss it.
  </Step>
</Steps>

<Frame>
  <img alt="Ghost Text" />
</Frame>

## Key capabilities

Ghost Text Completion provides several benefits for both new and experienced users:

* **Faster Input:** Write complex questions with fewer keystrokes.
* **Domain Discovery:** Identify specific terms, metrics, and data patterns unique to your organization.
* **Consistent Querying:** Reuse common styles and phrasing effortlessly.
* **Keyboard-First Workflow:** Maintain focus on your question without needing to use a mouse or navigate menus.

## Designed for

Text completion is key for:

* **Explorers** who are learning what questions they can ask of their data.
* **Builders** who write complex or technical queries.
* **Operators** who want faster access to insights.
* **Power Users** who value speed and keyboard-first workflows.

## FAQs

<AccordionGroup>
  <Accordion title="Do I have to use the suggestions?">
    No. Suggestions are entirely optional and are designed to stay out of your way if you choose to ignore them.
  </Accordion>

  <Accordion title="Are the suggestions relevant to my data?">
    Yes. The completions are specifically generated based on the context of the Domain you are currently using.
  </Accordion>

  <Accordion title="Does this slow down the typing experience?">
    No. The system is optimized to show suggestions quickly and update them seamlessly as you continue to type.
  </Accordion>

  <Accordion title="Does this provide user-level personalization?">
    Not currently. This feature focuses on Domain-specific terminology and common patterns. Individual user personalization is planned for a future update.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card icon="message-question" href="/using-wisdom-ai-everyday/ask-better-questions" title="Ask Better Questions">
    Learn strategies for phrasing your queries to get the most accurate results.
  </Card>

  <Card icon="link" href="/improve-wisdom-ai-responses/attach-files-to-chat" title="Using File Attachments in Chat">
    Attach a file to your WisdomAI chat to provide additional context for the session.
  </Card>
</CardGroup>


# Knowledge Playground
Source: https://docs.wisdom.ai/product-updates/february-2026/knowledge-playground



The Knowledge Playground is a dedicated workspace for turning business questions into reliable, reusable SQL and clear results. It provides a separate environment from your regular conversations, allowing you to generate AI-assisted drafts, iterate on logic, and validate accuracy before saving a final query for consistent use.

This feature helps you avoid messy iterations in chat threads, improves accuracy through testing, and speeds up the build-test-refine loop. This guide will walk you through the steps to start a question, iterate on your SQL, and save your finalized results.

## How it works

The process follows three steps to move from a plain-language idea to a validated, repeatable answer.

<Steps>
  <Step icon="messages-question" title="Start with a Question">
    Pick the appropriate data area and describe what you want to answer in plain language. You can also add optional hints if you already know specific filters or fields that the AI should include in the draft.
  </Step>

  <Step icon="code" title="Iterate on the SQL">
    Review the generated SQL and edit it manually as needed. **Retry** or update the code directly until the logic matches your intent.
  </Step>

  <Step icon="floppy-disk" title="Run, Validate, and Save">
    **Run** the query and inspect the results in the table and visualization views. Once you confirm the output is correct and tells the right story, click **Mark as reviewed** to keep the query for future reuse.
  </Step>
</Steps>

<video />

## Key capabilities

Knowledge Playground allows you to perform the following actions:

* **Draft SQL:** Create a starting point using plain-English questions.
* **Refine Logic:** Manually edit and rerun SQL until the output matches your requirements.
* **Inspect Results:** View data in table form and explore different visualizations to confirm accuracy.
* **Establish Reusability:** Save finalized queries for consistent reuse across your organization.

## FAQs

<AccordionGroup>
  <Accordion title="Can I edit the SQL after it is generated?">
    Yes. You can manually update the SQL and rerun it until the output is correct.
  </Accordion>

  <Accordion title="How do I know the results are accurate?">
    Run the query, inspect the output, and iterate until the results match your expectations. The goal is to validate the data before saving it for broader use.
  </Accordion>

  <Accordion title="Is this for experiments or production work?">
    Both. It is designed for quick experimentation and for turning those experiments into validated, production-ready queries.
  </Accordion>

  <Accordion title="Do I need special access to use it?">
    You may need elevated permissions depending on your workspace settings. If you cannot click **Run** or **Mark as reviewed**, check with your organization administrator.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card icon="wand-magic-sparkles" href="/product-updates/february-2026/context-builder-file-uploads" title="Context Builder - File uploads">
    Learn how to automatically generate suggestions from your existing documentation.
  </Card>

  <Card icon="layer-group" href="/setting-up-wisdom-ai/manage-domains/understand-domains" title="Understand Domains">
    Explore how to organize the data logic you create in the Knowledge Playground.
  </Card>
</CardGroup>


# MCP Visualizations in Dashboards
Source: https://docs.wisdom.ai/product-updates/february-2026/mcp-in-dashboards



The MCP Visualizations feature lets you turn insights generated in chat into live, refreshable dashboards. This includes visualizations generated by connected tools, scripts, or advanced analysis steps that go beyond standard SQL queries. Once you add these visualizations to a dashboard, they stay up to date automatically without requiring you to recreate the original conversation.

This feature ensures that advanced insights are treated as primary components of your dashboards, maintaining data consistency and respecting access controls during every refresh. This guide will walk you through the steps to move visualizations from chat to your dashboards.

## How it works

The process follows three steps to transition from a chat interaction to a permanent dashboard widget.

<Steps>
  <Step title="Ask and Explore" icon="messages-question">
    Start by asking a question in chat. The system may use connected tools or advanced analysis functionality to generate the data and a corresponding visualization.
  </Step>

  <Step title="Add to Dashboard" icon="chart-simple">
    When the system provides a visualization you want to track, click the **Add to dashboard** button. You can select an existing dashboard or create a new one as the destination.
  </Step>

  <Step title="Stay Fresh Automatically" icon="arrows-rotate">
    The dashboard widget stores the specific steps used to generate the data. The visualization refreshes with new data whenever the dashboard is loaded or updated, running the necessary analysis behind the scenes.
  </Step>
</Steps>

## Key capabilities

MCP Visualizations provide several advantages for maintaining complex data views:

* **Tool-Generated Charts:** Add visualizations to dashboards even if they were created by integrations or scripts rather than direct SQL.
* **Automatic Updates:** Keep your dashboards up to date without having to rerun individual chats.
* **Multi-Source Data:** Build dashboards that combine data coming from various tools and analysis steps.
* **Permission Enforcement:** All data refreshes respect individual user identity and access rules.

## Target users

The MCP in Dashboards feature is available to:

* **Admins** who care about access control and data consistency.
* **Data Administrators** or builders who combine tools and analysis to produce richer insights.
* **Explorers** or operators who rely on dashboards that must refresh reliably.

## FAQs

<AccordionGroup>
  <Accordion title="Does this work only with SQL-based data?">
    No. This feature supports visualizations created using connected tools and advanced analysis, not just standard SQL queries.
  </Accordion>

  <Accordion title="Will my dashboard refresh automatically?">
    Yes. Once added, the visualization refreshes using the same steps and logic that were used to produce it in the chat.
  </Accordion>

  <Accordion title="Are permissions respected on refresh?">
    Yes. Data refreshes run using the identity of the person viewing the dashboard. Access rules and row-level security are strictly enforced.
  </Accordion>

  <Accordion title="Can I edit or parameterize these widgets?">
    We currently support editing and customization through the **Visualization Editor**, allowing you to adjust styling and refine visual outputs. More advanced capabilities—such as global dashboard filters and deeper parameterization—are coming soon.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="Build Dashboards" icon="objects-column" href="/improve-wisdom-ai-responses/build-dashboards">
    Learn the basics of creating and organizing your dashboard layouts.
  </Card>

  <Card title="Knowledge Playground" icon="flask" href="/product-updates/february-2026/knowledge-playground">
    Experiment with questions and validate SQL before saving them for reuse.
  </Card>
</CardGroup>


# MCP Reviewed Queries
Source: https://docs.wisdom.ai/product-updates/february-2026/mcp-reviewed-queries



MCP Reviewed Queries extends the existing reviewed queries system to support visualizations generated from Model Context Protocol (MCP) tool calls. When you provide positive feedback on an MCP-generated visualization, it becomes a high-quality example that the system uses to improve future responses for similar queries.

This feature creates a continuous learning loop in which your everyday interactions help the system understand what a correct answer looks like, forming patterns it can repeat. This guide will walk you through the steps for asking questions, approving results, and improving the system's accuracy over time.

## How it works

The process follows three steps to turn a single correct answer into a repeatable pattern for the system.

<Steps>
  <Step icon="messages-question" title="Ask a Question">
    Start by asking a question in chat that requires a connected tool to generate a response. The system will use the tool to provide data and a corresponding visualization.
  </Step>

  <Step icon="thumbs-up" title="Approve the Result">
    Inspect the visualization and the data provided. If the result is accurate and meets your requirements, click the **Thumbs Up** icon. This action flags the response as a validated example.

    <Note>
      Currently, feedback icons (thumbs-up and thumbs-down) appear only for responses containing charts or structured data. Feedback for text-only responses is not yet supported but will be available in a future update.
    </Note>
  </Step>

  <Step icon="sparkles" title="Get Better Answers">
    The system automatically uses that approved example to guide its logic when answering similar questions in the future. Over time, these reviewed queries reduce inconsistency and ensure the system follows your preferred patterns.
  </Step>
</Steps>

## Key capabilities

MCP Reviewed Queries allow you to improve system performance without complex manual setup:

* **Automatic Improvements:** Enhance tool-based answers simply by interacting with the chat.
* **Reusable Examples:** Turn one-off correct visualizations into reference points for the AI.
* **Pattern Recognition:** Help the system learn real-world usage patterns that metadata and schemas alone cannot capture.
* **Consistency:** Reduce variations in how the system responds to similar questions across your organization.

## Target users

The MCP Reviewed Queries feature is available to **Admins** and **Explorers** who rely on validated query patterns to ensure accuracy, reduce inconsistency, and maintain high-quality data standards across their organization.

## FAQs

<AccordionGroup>
  <Accordion title="What happens when I click the thumbs-up icon?">
    The system treats that specific result as a high-quality example. It uses the logic and output of that interaction to guide its handling of similar requests in the future.
  </Accordion>

  <Accordion title="Do I need to manage these examples manually?">
    No. The learning process happens automatically once you approve a result. You do not need to perform additional configuration in the Domain settings.
  </Accordion>

  <Accordion title="Will this change the answers for other users?">
    Yes. Approved examples help the system respond more effectively to similar questions for all users within the Domain, while strictly respecting individual access controls and permissions.
  </Accordion>

  <Accordion title="Can I see or edit my approved examples?">
    Yes, domain data administrators can see and edit validated queries once created. Follow [this link](/setting-up-wisdom-ai/feedback-mechanisms/reviewed-queries) to learn more about reviewed queries.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card icon="thumbs-up" href="/explorers-feedback/provide-feedback-to-the-system" title="Provide Feedback to the System">
    Learn more about how different types of feedback help train WisdomAI.
  </Card>

  <Card icon="chart-pie" href="/product-updates/february-2026/mcp-in-dashboards" title="MCP Visualizations in Dashboards">
    Save your approved visualizations directly to live, refreshable dashboards.
  </Card>
</CardGroup>


# Features
Source: https://docs.wisdom.ai/product-updates/july-2026/july-features



Explore the latest features in WisdomAI's **July 2026** launch, focused on a redesigned chat experience and more flexible dashboard organization.

<CardGroup>
  <Card title="Chat" icon="message" href="/chat/overview">
    Ask in plain language, pick a reasoning mode, follow the AI's work step by step, and turn answers into reports, dashboards, and agents.
  </Card>

  <Card title="Dashboard Tabs" icon="table-columns" href="/dashboards/tabs">
    Split a dashboard into named tabs, move widgets between them, and share links that open on a specific tab.
  </Card>

  <Card title="Instant Filters" icon="filter" href="/dashboards/instant-filters">
    Narrow any results table in place. Filters apply in your browser, last for your session, and never change the underlying query.
  </Card>
</CardGroup>


# Features
Source: https://docs.wisdom.ai/product-updates/june-2026/june-features



Explore the latest features in WisdomAI's **June 2026** launch, focused on customizable AI workflows and flexible deployment options.

<CardGroup>
  <Card title="Skills" icon="wand-magic-sparkles" href="/setting-up-wisdom-ai/manage-domains/skills">
    Define reusable, versioned instructions that WisdomAI automatically loads for your team's recurring analysis and workflow patterns.
  </Card>

  <Card title="Deployment Models" icon="server" href="/deployment/deployment-models">
    Choose how WisdomAI runs (SaaS Hosted, Cloud-Prem, or On-Prem) based on your data residency and infrastructure requirements.
  </Card>
</CardGroup>


# Changelog
Source: https://docs.wisdom.ai/product-updates/march-2026/march-changelog



<Update label="Updates">
  ### 🤖 Metrics & Derived Column Copilots

  Defining business logic is now much easier with the AI-powered Metrics & Derived Column Copilot. Describe what you want in plain English, and WisdomAI generates the SQL, identifies the correct source table, and validates the expression against your warehouse before saving. The generated SQL is fully editable, allowing you to review and adjust it before adding it to your domain.

  **⚙️ How it works:**

  1. Access **Context** > **Metrics** tab > **Add Metric**
  2. Describe a metric or derived column in natural language and select **Generate**
  3. WisdomAI classifies the request, identifies the source table, and generates the SQL
  4. The query is validated against your warehouse
  5. Review and edit before saving

  <Frame>
    <img alt="Add A Metric" />
  </Frame>

  <Accordion title="FAQs">
    <AccordionGroup>
      <Accordion title="What is the difference between a metric and a derived column?">
        A metric is an aggregated value across multiple rows, such as total revenue. A derived column is a row-level calculation, such as combining first and last name. WisdomAI automatically determines which type fits your description.
      </Accordion>

      <Accordion title="Can I edit the generated SQL?">
        Yes. The right panel is a full SQL editor where you can modify the generated expression before saving it to your domain.
      </Accordion>
    </AccordionGroup>
  </Accordion>

  ### 📄 Tabular Extraction from Unstructured Datasets

  Turn unstructured files, such as PDF, Word, PowerPoint, plain text, Markdown, HTML, JSON, XML, YAML, and image formats into fully queryable tables. By defining fields with plain-English prompts, WisdomAI extracts values from multiple file formats and materializes them as structured data that can be queried, filtered, and joined with your existing datasets.

  **⚙️ How it works:**

  1. Upload files to a dataset in a domain, go to **Data Sources** > **Wisdom Storage**
  2. Select the uploaded files and click **Extract**
  3. Wait for the status to change to **Success,** and a new structured table will appear in your domain

  <Frame>
    <img alt="Extract" />
  </Frame>

  <Accordion title="FAQs">
    <AccordionGroup>
      <Accordion title="Can I query extracted data alongside my warehouse data?">
        Yes. The extracted table appears in your domain alongside your warehouse tables, and you can ask questions that join document data with warehouse data in a single natural-language query.
      </Accordion>

      <Accordion title="Can I update my field definitions after extraction?">
        Yes. If you update your field definitions, you can re-run the extraction, and the table will be updated automatically.
      </Accordion>
    </AccordionGroup>
  </Accordion>

  ### 📊 Warehouse Observability

  WisdomAI now provides visibility into how your warehouse is queried and how your team uses the platform. A system-generated domain, **WisdomAI Usage Metrics**, is automatically provisioned for every account.

  **⚙️ How it works:**

  A new system-generated domain is available to Admins in the domain list, featuring two pre-built dashboards:

  * **Warehouse Usage Dashboard**: Displays query-level details including execution time, rows returned, bytes scanned, and cache status.
  * **Usage Analytics Dashboard**: Tracks team adoption via conversation counts, active users, questions asked, and feedback rates.

  You can also ask natural-language questions directly within the domain, such as "How many queries did we run last week?"

  <Accordion title="FAQs">
    <AccordionGroup>
      <Accordion title="Where do I find the Warehouse Observability dashboard?">
        It appears in your dashboards list with a "System-generated" badge and is visible only to users with Data Admin or Admin roles.
      </Accordion>

      <Accordion title="How often is the data updated?">
        Query execution logs are written in real time. Enrichment data is updated every 2 hours for Snowflake and Databricks connections.
      </Accordion>

      <Accordion title="Is this domain visible to all users?">
        No. It is restricted to Data Admin and Admin roles. Regular users do not see it in the domain list.
      </Accordion>
    </AccordionGroup>
  </Accordion>

  ### 🔐 Login Method Memory

  WisdomAI now remembers your last sign-in to streamline future logins. Your previous method, Google, SSO, or email, is highlighted with a “Last used” badge, and email addresses are pre-filled when applicable. This information is stored locally in your browser and is not sent to any server.

  **⚙️ How it works:**

  1. Sign in using any available method
  2. WisdomAI stores the method locally in your browser
  3. On your next visit, the last method is highlighted with a "Last used" badge

  <Frame>
    <img alt="Log in screen with a “Last used” badge" />
  </Frame>

  <Accordion title="FAQs">
    <AccordionGroup>
      <Accordion title="Is my login information stored securely?">
        Yes. Only your login method and email address are saved, stored locally in your browser. No authentication tokens or passwords are ever stored.
      </Accordion>

      <Accordion title="Can I still sign in with a different method?">
        Yes. The "Last used" badge is a visual hint only and does not restrict your options. You can select any login method at any time.
      </Accordion>
    </AccordionGroup>
  </Accordion>
</Update>


# Features
Source: https://docs.wisdom.ai/product-updates/march-2026/march-features



The **March 2026** releases focus on streamlining user workflows and increasing WisdomAI's autonomy. This month, we are introducing "Reviewed Runs" to help agents learn from successful outputs while improving the daily experience with smarter login memory and real-time response notifications. These updates ensure that, whether you are building complex agents or conducting in-depth data analysis, WisdomAI remains a consistent and efficient partner in your data journey.

<Card title="Reviewed Runs in Agents" icon="robot" href="/setting-up-wisdom-ai/agents/reviewed-runs-in-agents">
  Learn how to set benchmarks for your agents using successful historical runs.
</Card>

## System updates

For a detailed list of all smaller improvements, bug fixes, and technical adjustments made throughout the month, please visit our dedicated Changelog section. This resource provides a continuous record of the incremental changes we make to the platform to improve your experience.

<Card title="View Changelog" icon="list-ul" href="/product-updates/march-2026/march-changelog">
  Access the full technical history of platform updates and fixes.
</Card>

***

<Note>
  **New content coming soon**

  We are currently updating our documentation to include detailed guides for the March release. These upcoming articles will provide step-by-step instructions on using our latest tools.

  Our team is finalizing these technical resources to ensure you have the information needed to implement these updates effectively. Check back shortly for the full documentation.
</Note>


# Context Builder - Connections
Source: https://docs.wisdom.ai/product-updates/spring-2026/context-builder-connections



Metric definitions, business rules, and table descriptions live across GitHub repositories, dbt YAML files, Looker models, and data catalogs — and the moment any of those sources changes, your domain starts falling behind. Context Builder closes that gap by connecting your domain directly to the systems where your business logic lives, powered by WisdomAI's Adaptive Context Engine, and keeps your domain's knowledge layer automatically synchronized.

## How it works

Context Builder follows a continuous synchronization lifecycle that maps external logic updates to your active domain across four functional stages.

<Steps>
  <Step title="Connect a source" icon="plug">
    Navigate to your domain's Overview page, select the Context Builder option, and click Build Content. A five-step wizard guides you through: choosing a source type, authenticating, scoping the extraction to a repository or branch, setting a schedule, and validating credentials. The connection appears in your list with a **PENDING** status.
  </Step>

  <Step title="Extract" icon="wand-magic-sparkles">
    The first run performs a full scan of the connected source. Subsequent runs are incremental, processing only changes since the last extraction. When a run completes, you receive an in-app notification with the count of items requiring attention and a direct link to the review screen.
  </Step>

  <Step title="Resolve conflicts" icon="code-merge">
    The context engine compares every incoming context object against what already exists in your domain. Conflicting entries appear side by side, so you can accept either version, write a custom merged definition, or defer. No automatic merges ever occur.
  </Step>

  <Step title="Publish" icon="check-double">
    Publishing a resolved extraction increments your domain version number and makes your updated knowledge layer available immediately across chat and dashboards.
  </Step>
</Steps>

<img alt="Gif showing the Context Builder connection flow" />

<Note>
  Looker and dbt projects stored in GitHub are available immediately via the GitHub connection. Atlan, Glean, and Collibra are in active development and will appear in the connection wizard as they go live.
</Note>

## Connection statuses

Use the table below to understand what each status means.

| Status              | Meaning                                                        |
| :------------------ | :------------------------------------------------------------- |
| **PENDING**         | Connection created, waiting for the first extraction to begin. |
| **EXTRACTING**      | Extraction is in progress.                                     |
| **AWAITING REVIEW** | Extraction complete. Items are ready for your review.          |
| **ACTIVE**          | All items reviewed and published.                              |
| **ERROR**           | Extraction failed. A manual re-run option is available.        |

## Supported sources

Currently supports the following source types, with more integrations on the way.

| Source                                  | Status                                                                    |
| :-------------------------------------- | :------------------------------------------------------------------------ |
| GitHub (includes Looker and dbt in Git) | Available                                                                 |
| Query history                           | Available for enabled domains. Contact your Solutions Engineer to confirm |
| Atlan, Glean, Collibra                  | In active development                                                     |

## Target users

Context Builder is available to **Admins** and **Domain Admins**, who connect sources, configure schedules, review extractions, and publish changes.

## User Stories

See real stories of how WisdomAI improvements are helping solve real user problems:

<Tabs>
  <Tab title="Story 1">
    **Keeping Metrics Aligned After a dbt Model Refactor**

    A data engineering team refactors their `revenue` model in dbt, changing the grain and updating metric definitions across three YAML files. Previously, a domain lead would only discover the discrepancy after getting a wrong answer in chat. With Context Builder, the latest incremental extraction picks up the dbt changes automatically. The domain admin receives a notification: "3 conflicts detected. ARR definition differs between dbt and existing domain." They open the side-by-side diff, accept the updated dbt definition for ARR, write a custom merged definition for one edge case, and publish. The domain reflects the new business logic before analysts start their day.
  </Tab>

  <Tab title="Story 2">
    **Bootstrapping a New Domain from a GitHub Monorepo**

    A new domain is being stood up for a fintech product team. Their entire metric layer lives in a GitHub monorepo: dbt YAML files, SQL pipeline configs, README documentation, and metric definitions.

    Instead of manually exporting and uploading files, the domain admin connects their GitHub org via Context Builder, scopes to the relevant repositories, and triggers an initial extraction. Within the hour, 200+ context objects (metric definitions, JOIN patterns, business glossary entries, and table descriptions) surface for review. The admin bulk-approves the high-confidence entries, edits a handful of edge cases, and publishes. A domain that would have taken days of manual entry is operational by afternoon.
  </Tab>
</Tabs>

## FAQs

<AccordionGroup>
  <Accordion title="Does anything get published to my domain automatically?">
    No. Every extraction goes through a human-in-the-loop review. An auto-accept option is available if you want to approve all suggestions at once, but nothing publishes without your explicit action.
  </Accordion>

  <Accordion title="What if I close my browser mid-extraction?">
    Nothing is interrupted. Extraction jobs run as persistent background processes. You can return at any time and the job will still be running or waiting for review.
  </Accordion>

  <Accordion title="What if I publish something and realize it was wrong?">
    Open the version history panel, find the prior version, and restore it with a single confirmation step. History is append-only, nothing is ever permanently deleted.
  </Accordion>

  <Accordion title="How is this different from Context Builder - File uploads?">
    Context Builder - File uploads is a one-time, manual flow designed for bootstrapping. Context Builder - Connections connects to the live source system, extracts automatically on a schedule, and keeps the domain continuously aligned without manual export or file handling.
  </Accordion>

  <Accordion title="What happens if I disconnect a source?">
    The connection is removed and credentials are revoked immediately. Context already published to your domain remains in place and is not removed automatically.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="Advanced data modeling" icon="sitemap" href="/setting-up-wisdom-ai/advanced-data-modeling-creating-context">
    Learn how to manually create relationships, metrics, and context in your domain.
  </Card>

  <Card title="Domain Health" icon="heart-pulse" href="/product-updates/spring-2026/domain-health">
    Measure how effectively your domain's knowledge layer is producing correct answers.
  </Card>
</CardGroup>


# Domain Health
Source: https://docs.wisdom.ai/product-updates/spring-2026/domain-health



Domain Health gives domain administrators a clear, scored signal of whether a domain is well-configured and ready for reliable use. It evaluates three dimensions (schema, context, and usage), combines them into a single score, and surfaces a prioritized list of specific improvements you can accept or decline with one click. This guide walks you through how the score is calculated, how to run an analysis, and how to act on recommendations.

## How it works

A combination of deep data evaluations with actionable workflows across four progressive stages to ensure your data models are production-ready.

<Steps>
  <Step title="Health dimensions" icon="chart-network">
    Domain Health evaluates three dimensions:

    * **Schema quality** assesses whether the domain's table and column definitions are clear and usable. It flags cryptic or ambiguous names, overlapping names that lack descriptions, and missing join relationships between tables that are commonly queried together.
    * **Context quality** re-runs your Reviewed Queries through the system and evaluates whether the generated SQL matches expected output. The Context Quality Agent diagnoses root causes, knowledge conflicts, stale definitions, contradictions  and proposes specific fixes.
    * **Usage signals** track conversation volume, negative feedback rate, and limited-context rate.
  </Step>

  <Step title="Running an analysis" icon="play">
    Click **Run Analysis** in the Domain Health tab. Use this before a planned rollout or after a significant domain change.
  </Step>

  <Step title="Recommendations" icon="lightbulb">
    After each analysis, WisdomAI surfaces a prioritized list of specific actions:

    | Priority   | What it covers                                                        |
    | :--------- | :-------------------------------------------------------------------- |
    | **HIGH**   | Direct SQL or knowledge fixes with a measurable impact on eval scores |
    | **MEDIUM** | Knowledge additions for uncovered tables or ambiguous definitions     |
    | **LOW**    | Hygiene improvements such as adding descriptions or renaming columns  |

    Each recommendation can be accepted (applied immediately) or declined (dismissed for 90 days).
  </Step>

  <Step title="End-user readiness signals" icon="user-check">
    When a domain's health score falls below the production-ready threshold, a persistent banner appears in chat and explorer interfaces. Lower-health domains also display a **Learning** chip next to the domain name in the selector dropdown, visible to all users.
  </Step>
</Steps>

<video />

## Target users

Domain Health is available to:

* **Domain Admins**: Run analyses, review recommendations, and monitor scores over time.
* **Data Analysts**: See the readiness banner and Learning chip when a domain is below threshold.

## FAQs

<AccordionGroup>
  <Accordion title="How often does the automated health check run?">
    Analysis runs are currently triggered manually from the Domain Health tab. Automated weekly runs are on the near-term roadmap.
  </Accordion>

  <Accordion title="Does accepting a recommendation apply changes immediately?">
    Yes. The change takes effect on the next query.
  </Accordion>

  <Accordion title="My domain has no Reviewed Queries. What happens to the context quality score?">
    Without Reviewed Queries, context quality cannot be measured. Adding and reviewing queries is the primary way to improve this score.
  </Accordion>

  <Accordion title="What's the difference between schema quality and context quality?">
    Schema quality evaluates the structural layer, whether names are clear, joins are defined, and tables are accessible. Context quality evaluates the knowledge layer, whether the domain's curated content produces correct answers on queries it has been taught.
  </Accordion>

  <Accordion title="Does Domain Health work for MCP data sources?">
    Support for MCP sources is on the near-term roadmap. The current release covers SQL-based domains.
  </Accordion>

  <Accordion title="What is the Learning chip?">
    A small chip displayed next to a domain name in the selector dropdown when the domain's health score is below the production-ready threshold.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="Advanced data modeling" icon="sitemap" href="/setting-up-wisdom-ai/advanced-data-modeling-creating-context">
    Learn how to add the metrics, joins, and context that improve your schema and context quality scores.
  </Card>

  <Card title="Context Builder - Connections" icon="rotate" href="/product-updates/spring-2026/context-builder-connections">
    Keep your domain's knowledge layer synchronized automatically as your source systems change.
  </Card>
</CardGroup>


# Parameterized Agents
Source: https://docs.wisdom.ai/product-updates/spring-2026/parameterized-agents



Parameterized Agents let you define an input schema on any agent so it accepts runtime variables, an org ID, a department name, a list of assets to analyze, or a recipient email. One agent definition can then run for multiple subscribers, each with its own parameter values. Every run executes with the agent owner's data access, not the subscriber's. This guide walks you through defining input parameters, configuring subscriptions, and managing templates.

## How it works

An adaptable execution workflow that maps central logic templates to individual subscriber environments through a four-stage process.

<Steps>
  <Step title="Define input parameters" icon="sliders">
    Open your agent in edit mode and define an input schema: variable name, type, description, and an optional default value. Supported types are text, number, boolean, email, and Slack.
  </Step>

  <Step title="Collect runtime parameters" icon="input-text">
    When a user manually triggers a parameterized agent, a generated input form collects their values. Submitted values are injected wherever you reference the parameter throughout the agent's prompts and node configurations.
  </Step>

  <Step title="Iterate over parameter value sets" icon="arrows-repeat">
    Provide multiple value sets and the agent runs once per set, each in an independent context. This is how you iterate over a collection, since input parameters don't support a list type.
  </Step>

  <Step title="Manage subscriptions and templates" icon="users-gear">
    Admins can publish an agent as a template and push-enroll users as subscribers. Each subscriber has their own parameter bindings. When the agent runs:

    * Each subscriber receives a run with their own parameter values. The run executes with the agent owner's data access.
    * Runs execute under the runner's (owner's) identity, and RLS/CLS are enforced based on the runner's permissions, not the subscriber's.
    * Failures are isolated: one subscriber's error does not affect any other subscriber's run.
  </Step>
</Steps>

### Subscription visibility

Depending on your subscription status, agents will appear in one of two distinct tabs within your workspace:

| Tab            | What it shows                                                                                     |
| :------------- | :------------------------------------------------------------------------------------------------ |
| **My Agents**  | Agents you created and agents you are subscribed to. Subscribed agents display a Subscribed pill. |
| **Agent Runs** | A history of each agent execution, with logs, node-by-node inspection, and reviewed runs.         |

## Target users

Parameterized Agents are available to:

* **Admins**: Define input schemas, publish templates, and push-enroll subscribers.
* **Agent Builders**: Build parameterized workflows and test with different input values.
* **All users**: Once push-enrolled by an admin, trigger agents with their own parameters via the input form.

## FAQs

<AccordionGroup>
  <Accordion title="What parameter types are supported?">
    Text, number, boolean, email, and Slack. File and attachment input support is on the roadmap.
  </Accordion>

  <Accordion title="Is scheduled fan-out supported?">
    Yes. Scheduled fan-out is supported in the latest version.
  </Accordion>

  <Accordion title="Does each subscriber's run use their own row-level security?">
    No. Runs execute under the runner's (owner's) identity, and RLS/CLS are enforced based on the runner's permissions, not the subscriber's.
  </Accordion>

  <Accordion title="Can subscribers see each other's run logs or outputs?">
    No. Each subscriber can only see their own runs. Run logs and outputs are not shared across subscribers.
  </Accordion>

  <Accordion title="Can an admin update a template after users have subscribed?">
    Yes. Template updates propagate to all subscribers on the next run. Existing subscriber parameter bindings remain valid unless the input schema changes in a breaking way.
  </Accordion>

  <Accordion title="What is the difference between a subscriber and a viewer?">
    Viewer access (IAM) controls who can see that the agent exists at all. Subscription controls who runs the agent and receives its output. These operate independently—an admin can push-enroll a subscriber, which implicitly grants viewer access if it isn't already present.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="Agents" icon="robot" href="/setting-up-wisdom-ai/agents/agents">
    Get an overview of what agents are and the two ways you can build them.
  </Card>

  <Card title="Build an Agent in Visual Mode" icon="diagram-project" href="/setting-up-wisdom-ai/agents/visual-mode">
    Step-by-step guide to building your first Visual Mode agent.
  </Card>

  <Card title="Create an Agent" icon="wand-magic-sparkles" href="/setting-up-wisdom-ai/agents/tutorial-create-agent">
    Learn the basics of setting up a new AI agent in Prompt Mode.
  </Card>

  <Card title="Understand domains" icon="layer-group" href="/setting-up-wisdom-ai/manage-domains/understand-domains">
    Learn how domains organize the data logic and permissions your agents run against.
  </Card>

  <Card title="Domain Health" icon="heart-pulse" href="/product-updates/spring-2026/domain-health">
    Measure and improve your domain's readiness before opening it to subscribers.
  </Card>
</CardGroup>


# Changelog
Source: https://docs.wisdom.ai/product-updates/spring-2026/spring-changelog



<Update label="Updates">
  ### 🧠 Knowledge signals from chat

  Every conversation where a user corrects an answer, clarifies a metric, or states a business rule is a potential source of domain knowledge. Until now, that signal was lost after the chat ended. Knowledge Signals from Chat lets domain admins surface those insights from any conversation and promote them directly to the domain knowledge base with a single review step.

  **⚙️ How it works:**

  1. Open any conversation in your domain
  2. Click the brain icon (**Knowledge Suggestions**) in the chat controls bar
  3. Review the suggested entries; each one is editable before accepting
  4. **Accept**, **Decline**, or edit inline, then accept. Nothing is published automatically

  <Accordion title="FAQs">
    <AccordionGroup>
      <Accordion title="Does accepting a suggestion take effect immediately?">
        Yes. Once accepted, the entry is written to the domain knowledge base and available for retrieval on the next query.

        <Tip>
          To edit a suggestion, use the inline text editor. Click into the text, make your changes, and then click **Accept**. The edited version is the one that gets saved.
        </Tip>
      </Accordion>

      <Accordion title="What if I accept something that's wrong?">
        Navigate to the Domain Knowledge tab. The confirmation notification after acceptance includes a direct link. You can edit or delete the entry there.
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Note>
    The Knowledge Suggestions panel is currently in early access while we refine its performance and quality. Review and edit suggestions before accepting.
  </Note>

  <Note>
    Currently available to Domain Admins only. This feature will extend to Explorers in a future release.
  </Note>

  ### 🗂️ Agent version control

  Agent edits no longer modify the live version. Every change creates a draft, leaving the published version running undisturbed until you're ready. Publishing a new version increments the version number and locks that version. Run logs are permanently tied to the version that executed them, so reviewing a past run always shows the correct graph and configuration.

  **⚙️ How it works:**

  1. Edit the agent. A draft is created automatically, and the published version continues running
  2. Test using **Preview** before committing any changes
  3. Click **Publish**. The draft is locked as the new published version, and the version number increments
  4. Open any past run in the **Run Visualizer** to see the exact version used for that run

  <Frame>
    <img alt="Agent Versioning 01" />
  </Frame>

  <Accordion title="FAQs">
    <AccordionGroup>
      <Accordion title="Does publishing affect runs currently in progress?">
        No. In-progress runs complete against the version they were dispatched on. Publishing only affects runs triggered after the publish.
      </Accordion>

      <Accordion title="Can I roll back to a previous published version?">
        Version history is retained and viewable. One-click rollback is on the near-term roadmap.
      </Accordion>

      <Accordion title="Can multiple people edit the same agent simultaneously?">
        Each agent has one draft at a time. Concurrent edit locking is on the roadmap.
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Tip>
    We always recommend testing your drafts before publishing. Once published, the draft becomes the locked published version. Testing beforehand is especially important for agents with scheduled runs or production recipients.
  </Tip>

  ### ✅ Agent Reviewed runs

  Reduce agent non-determinism by marking successful runs as golden examples. When a run is marked as Reviewed, its full execution history (LLM interactions, tool calls, and outputs) is injected into future runs of the same prompt as historical context. This anchors SQL patterns, output formatting, and decision logic to a run you've confirmed is correct.

  **⚙️ How it works:**

  1. Open an agent and click **View Runs** to access its **Previous Runs**
  2. Click **Mark as reviewed** on a successful run, a green **Reviewed** chip appears on the run header
  3. On future runs, WisdomAI fetches up to 3 matching reviewed conversations and injects them as context before generating a response

  <Frame>
    <img alt="Reviewed Run" />
  </Frame>

  | Color/Status | Meaning                               |
  | ------------ | ------------------------------------- |
  | `green`      | Completed successfully                |
  | `red`        | Failed or errored                     |
  | `gray`       | Did not execute (branch not taken)    |
  | `spinning`   | Currently in progress (for live runs) |

  <Accordion title="FAQs">
    <AccordionGroup>
      <Accordion title="How many reviewed runs does the system use at once?">
        Up to 3, selected by most-recently-reviewed first.
      </Accordion>

      <Accordion title="Can I un-review a run?">
        Yes. The action can be toggled. Removing reviewed status removes the run from the reference pool immediately.
      </Accordion>
    </AccordionGroup>
  </Accordion>

  ### 🔍 Agent Run visualizer

  The Run Visualizer renders a full execution trace of any past or live agent run directly on the agent graph: every node color-coded by status, with a detail panel showing inputs, outputs, tool calls, and timing. Because the graph displayed is always the version used for that specific run, it serves as a reliable audit trail even after the agent has been updated.

  **⚙️ How it works:**

  * Go to **Agents**, open an agent, and navigate to **Previous Runs**
  * Click any run to open its Run Visualizer
  * Click any node to see its input, output, tool calls, and execution duration
  * For live runs, nodes update in real time as the execution progresses

  <Frame>
    <img alt="Run Visualizer" />
  </Frame>

  <Accordion title="FAQs">
    <AccordionGroup>
      <Accordion title="Does the visualizer show the current agent version or the version that ran?">
        Always the version used for that run. If the agent has been edited and republished since, historical runs still show the original version.
      </Accordion>

      <Accordion title="Does this work for both Visual Mode and Prompt Mode agents?">
        Yes. Visual Mode agents show the full node graph. Prompt Mode agents show a structured timeline of LLM calls, tool invocations, and outputs.
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Tip>
    You can share a specific run’s visualizer link with colleagues using the direct URL included in email and Slack delivery notifications. Access is still subject to the agent’s permissions.
  </Tip>

  ### 🔌 Dremio connector

  WisdomAI now connects natively to Dremio Cloud and Dremio Software via Apache Arrow Flight, enabling natural-language queries against your data lakehouse without manual dialect configuration or JDBC workarounds. WisdomAI handles schema crawling, view detection, and Dremio-specific SQL generation are handled automatically. Enterprise deployments using internal CA certificates are supported via custom certificate upload during setup.

  **⚙️ How it works:**

  1. Go to **Connections** > **Add connection** and select **Dremio**
  2. Enter the Flight endpoint host and port
  3. Provide authentication credentials: Personal Access Token for Dremio Cloud; username/password or PAT for Dremio Software
  4. Configure TLS and optionally upload a custom root certificate for internal CA environments
  5. WisdomAI crawls the schema and makes the domain available for natural-language queries
  6. Define the source path scope (Dremio's multi-level namespace paths are supported)

  <Frame>
    <img alt="Dremio" />
  </Frame>

  <Accordion title="FAQs">
    <AccordionGroup>
      <Accordion title="Are both Dremio Cloud and Dremio Software supported?">
        Yes. Dremio Cloud uses a Personal Access Token. Dremio Software supports username/password via Flight handshake or a PAT.
      </Accordion>

      <Accordion title="What SQL dialect does WisdomAI generate for Dremio?">
        WisdomAI automatically generates SQL in Dremio's dialect. No manual configuration is required.
      </Accordion>

      <Accordion title="Is there a row limit on queries executed against Dremio?">
        WisdomAI applies its standard query result limits. Dremio's own resource controls also apply.
      </Accordion>
    </AccordionGroup>
  </Accordion>

  ### 📊 Dashboard improvements

  Three updates make editing, exporting, and working with dashboard tiles faster and more reliable.

  * **Inline tile renaming**: Rename a dashboard tile by hovering over the title and clicking to edit it directly, without navigating through the overflow menu. Viewers see a plain title with no edit option, keeping the interface clean for non-editors.
  * **Tile export and copy**: Exporting and copying dashboard tiles now includes a reorganized menu, live progress tracking for CSV exports, and image exports that exclude UI chrome.
  * **SQL widget trajectory**: The **Add SQL Tile** flow now creates a trajectory at widget creation time, matching the behavior of chat-created widgets. All dashboard widgets now carry trajectory lineage, supporting trajectory-based editing going forward.

  ### 🔌 BigQuery OAuth available for all users

  BigQuery OAuth is now available on all deployments without requiring a per-environment feature flag. When setting up a BigQuery connection, the "Enable OAuth for user queries" checkbox appears in the connection form for all users.

  ### 🔐 Streamlined email domain allowlist enforcement

  The email domain allowlist is now enforced only at account-creation time, improving response times for all requests. A notice in the settings clarifies that changes to the allowlist are not retroactive: existing users are unaffected by updates to the list.

  ### ⌨️ Cmd+Enter shortcut for SQL generation in Playground

  Press Cmd+Enter (or Ctrl+Enter on Windows and Linux) in the Playground to trigger SQL generation without reaching for the **Generate SQL** button.

  ### 📄 10× faster chat exports

  Exporting large chat histories is now significantly faster and less likely to cause system interruptions, with a 10× reduction in memory usage during the export process.

  ### 🧠 Domain Health replaces the Suggestions tab

  For admins and superusers, **Domain Health** is now the single place to review and act on modeling suggestions. The **Suggestions** tab is no longer shown for these roles, and any existing bookmarks to the Suggestions page redirect to the domain Overview.
</Update>


# Features
Source: https://docs.wisdom.ai/product-updates/spring-2026/spring-features



Explore the latest features in WisdomAI's **Spring 2026** launch, focused on agent reliability, automated domain intelligence, and deeper embeddability.

<CardGroup>
  <Card title="Parameterized Agents" icon="sliders" href="/product-updates/spring-2026/parameterized-agents">
    Run one agent for multiple users or inputs, with each run scoped to its recipient's data permissions and parameters.
  </Card>

  <Card title="Context Builder - Connections" icon="rotate" href="/product-updates/spring-2026/context-builder-connections">
    Connect your domain directly to GitHub and dbt repositories and keep your knowledge layer synchronized on a schedule.
  </Card>

  <Card title="Domain Health" icon="heart-pulse" href="/product-updates/spring-2026/domain-health">
    A scored readiness signal across schema, context, and usage, with a prioritized list of actionable improvements.
  </Card>

  <Card title="Embedded Analytics SDK" icon="code" href="/integrations/embeddings/sdk/sdk-overview">
    A React component library for embedding WisdomAI dashboards natively inside your product, with full theming and host-controlled layout.
  </Card>
</CardGroup>


# Limits and Quotas
Source: https://docs.wisdom.ai/reference-library/limits-and-quotas



<Tip>
  Page Under Construction
  This page is currently being developed. We're actively working to provide you with helpful and accurate documentation for WisdomAI.

  Please check back soon, new content is on the way!
</Tip>


# Add Domain-Specific Knowledge
Source: https://docs.wisdom.ai/setting-up-wisdom-ai/add-domain-specific-knowledge



To improve how WisdomAI understands and answers user queries, you can add your business knowledge to your Domain. This will help refine data interpretation, align responses with business definitions, and improve overall accuracy.

Here's how to do it:

1. Select the relevant **Domain** from your Domains dashboard.
2. Navigate to the **Context** tab.
3. Select the **Knowledge** tab inside the Context section.
4. Click the **+ Add Knowledge** button to begin a new entry and add natural language context.
   * Alternatively, **upload a file** containing domain-specific information.
   * Here, you can also **download** the context entries in a CSV-format file.

<Frame>
  <img alt="NEW Add Knowledge Steps" />

  <img alt="NEW Add Knowledge Steps" />
</Frame>

### Further Knowledge configuration

Other key features within the Domain section help you define and refine contextual information for accurate AI responses.

* **Data Sources**: This tab is where you manage and model the raw data structure to make it queryable and insightful within the platform. To enhance Knowledge from the Data Sources tab, you can:
  * [**Document Tables and Columns**](/setting-up-wisdom-ai/manage-tables-columns/document-tables-and-columns): Write clear, natural language descriptions for tables and columns to help the AI interpret schema elements accurately.
  * [**Define Metrics with SQL**](/improve-wisdom-ai-responses/how-to-create-metrics): Use SQL formulas to define key metrics and calculations, ensuring consistent, precise responses.

## Next steps

<CardGroup>
  <Card title="Auditing" icon="clipboard-list" href="/using-wisdom-ai-everyday/auditing">
    Organize insights by tagging chats, navigating history, and sharing vetted answers with your team.
  </Card>

  <Card title="Provide Feedback to the System" icon="thumbs-up" href="/setting-up-wisdom-ai/feedback-mechanisms/provide-feedback-to-the-system">
    Learn how to rate answers and provide corrections to improve the system's accuracy.
  </Card>

  <Card title="Validate and Test Answers" icon="check-double" href="/improve-wisdom-ai-responses/validate-and-test-answers">
    Understand the methods for verifying the correctness and reliability of generated answers.
  </Card>

  <Card title="Advanced Data Modeling" icon="sitemap" href="/setting-up-wisdom-ai/advanced-data-modeling-creating-context">
    Define relationships and Knowledge in your data to enable more powerful analysis.
  </Card>
</CardGroup>


# Advanced Data Modeling: Creating Context
Source: https://docs.wisdom.ai/setting-up-wisdom-ai/advanced-data-modeling-creating-context



This article, intended for Admin users and Data Administrators, details the three primary methods for creating and curating Context to improve AI-powered analytics in responses. The main goal of this page is to explain the following concepts:

* [Formal Semantic Modeling: Model data using a formal semantic layer.](#formal-semantic-modeling)
* [Natural Language Knowledge: Enrich the AI's understanding with natural language.](#natural-language-knowledge)
* [Feedback-Based Context: Improve accuracy by directly incorporating user feedback.](#feedback-based-context)

## Formal Semantic Modeling

This section outlines the core concepts behind translating raw database structures into a well-defined, business-friendly semantic layer. This allows users to interact with data in familiar business terms.

### Table and column documentation

Properly documenting tables and columns provides foundational context to enable effective analytics. For each table, provide a clear, plain-English description of what the table represents, and include a statement of what each row's granularity represents, such as, "*Each row represents a single sales transaction from a point-of-sale system*". For each column, define a user-friendly Display Name, a Description in business terms, and a Display Format.

<Note>
  For a detailed guide on this topic, please refer to our article [Document Tables and Columns](/setting-up-wisdom-ai/manage-tables-columns/document-tables-and-columns).
</Note>

<Frame>
  <img alt="Image showing the Document Tables interface" />

  <img alt="Image showing the Document Tables interface" />
</Frame>

### Defining Entities

An Entity is a business-critical object, such as "Account" or "Product," represented within the Data Graph. In WisdomAI, these entities are prioritized in the chat experience to enhance user understanding and interaction.

When an entity is defined, WisdomAI automatically improves the chat response by:

* Replacing unintuitive ID columns with human-readable names.
* Displaying related columns to provide a more complete Context.
* Providing direct, automatically resolved answers.
* Generating external links to source systems, like Salesforce for an "Opportunity" or Zendesk for a "Case."

Creating an entity involves grouping columns from one or more data source tables into a logical business object that mirrors a real-world concept. This process includes naming the entity, mapping it to its underlying data tables, and configuring its properties, such as its primary key and the field that will serve as its default display name.

<Frame>
  <img alt="Image showing the Entity Mapping option" />

  <img alt="Image showing the Entity Mapping option" />
</Frame>

### Establishing relationships

Define the connections between entities to enable precise data-model navigation. Create relationships by selecting the source and target tables and their corresponding attributes. You must configure the relationship's cardinality (1:1, 1:M, M:M). 

<Warning>
  Use join cardinality carefully, as incorrect settings can drastically change query results and lead to missing or duplicated data.
</Warning>

<Frame>
  <img alt="Image showing the Create Relationship modal" />

  <img alt="Image showing the Create Relationship modal" />
</Frame>

### Creating Metrics

Define standard calculations to enforce consistent business logic and simplify analysis for end-users. This involves creating Metrics, quantifiable business calculations such as Revenue or Conversion Rate, defined with SQL expressions and reusable across the organization.

<Note>
  For a comprehensive guide on this topic, including step-by-step instructions and detailed examples, please refer to our full article, [How to Create Metrics](/improve-wisdom-ai-responses/how-to-create-metrics).
</Note>

<Frame>
  <img alt="Image showing the Metrics Tab" />

  <img alt="Image showing the Metrics Tab" />
</Frame>

### Data model augmentation

Augment your data model with derived tables and columns using standard SQL syntax. Derived Columns and Tables are calculated fields or virtual tables created with SQL to clean, enrich, or simplify complex underlying data. These augmentations can be used to:

* **Clean Data:** Standardize formats, handle missing values, fix inconsistencies.
* **Enrich Data:** Add business context, derive new metrics, categorize values.
* **Simplify Analysis:** Create business-friendly views of complex underlying data.

<img alt="Image showing the Derived Table" />

<img alt="Image showing the Derived Table" />

## Natural language Knowledge

This section covers the methods for providing the AI with unstructured, domain-specific knowledge that is difficult to capture in a formal data model, such as business rules or specific terminology.

### Manual Knowledge entry

Add domain-specific knowledge, rules, or naming conventions in natural language sentences to guide the AI’s understanding. An example is: "*Regions are the same as Territories*." This improves accuracy by helping the system interpret ambiguous terms and captures knowledge that does not exist in the database schema. It is crucial to validate the impact of manual entries by asking a question in the chat interface to see if the response is as expected.

<Note>
  To learn how to add Knowledge, read the article [Add Domain-Specific Knowledge](/setting-up-wisdom-ai/add-domain-specific-knowledge). There, you will find an example of how the response changes after you add Knowledge.
</Note>

<Frame>
  <img alt="Image showing the Knowledge Tab" />

  <img alt="Image showing the Knowledge Tab" />
</Frame>

### Importing unstructured Context (beta)

Enhance the AI’s Context by importing knowledge directly from existing business and technical documents. This process is handled through the 'Chat' window, which provides an interactive interface for selectively extracting Context. Supported information types that can be imported include:

* **ERD Diagrams:** Extract entity relationships from diagram images.
* **dbt Files:** Import transformation logic and metric definitions.
* **SQL Queries**: Learn from existing queries and report definitions.
* **Data Dictionaries:** Import field descriptions and business definitions.
* **Business Glossaries:** Learn industry and company-specific terminology.
* **CSV files:** Import master data, mapping tables, or lists of business entities to learn categorical values and key dimensions (e.g., product catalogs, regional hierarchies, or customer segments).

<Note>
  To learn how to upload CSV files, read the [Basic Tutorial](/setting-up-wisdom-ai/basic-tutorial-connect-and-test#3-upload-csv-files-optional). Speak with your WisdomAI representative to enable any of the other features.
</Note>

## Feedback-based Context

This section describes the continuous learning loop, where direct user feedback on AI-generated responses is used to validate and refine the system's knowledge and accuracy over time.

### Creating Reviewed Queries

Create a library of pre-vetted queries by pairing a natural language question with its ideal SQL response. This is the most critical aspect of Context for the language model to understand your data. Reviewed Queries are created from the chat experience by giving a "thumbs up" to a correct response, then confirming the natural-language question that the SQL code answers. This process ensures accuracy and consistency for common business questions.

<Note>
  To learn more about validating your queries, refer to the [Reviewed Queries](/setting-up-wisdom-ai/feedback-mechanisms/reviewed-queries) article.
</Note>

<img alt="Image showing the Reviewed Queries tab" />

<img alt="Image showing the Reviewed Queries tab" />

### Advanced feedback and corrections

Provide direct feedback to correct the AI and allow power users to refine the underlying SQL, creating a robust knowledge base from user interactions. Users can mark responses as incorrect to flag them for review.

* [**SQL Editing for Power Users**](/improve-wisdom-ai-responses/validate-and-test-answers#1-edit-the-sql-query): Each answer in the chat includes an "Edit" button that allows Admin users to modify the underlying SQL query directly to fix calculation issues, add joins, or modify filters. Edited queries become part of the system's knowledge base for handling similar questions in the future.
* [**Negative Feedback Workflow**](/setting-up-wisdom-ai/feedback-mechanisms/monitor-negative-feedback): Negative feedback is channeled to administrators for review. This is managed through visual indicators that highlight chats with negative feedback and automatic email notifications sent to administrators for prompt attention.

<img alt="Image showing the Sql Editing Option" />

<img alt="Image showing the Sql Editing Option" />

## **Next steps**

<CardGroup>
  <Card title="Auditing" icon="clipboard-list" href="/using-wisdom-ai-everyday/auditing">
    Review query history and system activity to ensure compliance and accuracy.
  </Card>

  <Card title="Provide Feedback to the System" icon="thumbs-up" href="/setting-up-wisdom-ai/feedback-mechanisms/provide-feedback-to-the-system">
    Learn how to rate answers and provide corrections to improve the system's accuracy.
  </Card>

  <Card title="Validate and Test Answers" icon="check-double" href="/improve-wisdom-ai-responses/validate-and-test-answers">
    Understand the methods for verifying the correctness and reliability of generated answers.
  </Card>
</CardGroup>


# Agent Best Practices
Source: https://docs.wisdom.ai/setting-up-wisdom-ai/agents/agent-best-practices



Building an agent that runs reliably in production requires more than just connecting nodes. The practices below are distilled from the patterns that consistently produce the highest-quality agent outputs across WisdomAI. They cover the decisions that most affect output quality: how you write instructions, set trigger conditions, choose a schedule, and format the output. Apply them when building a new agent and when debugging one that isn't behaving as expected.

## Writing effective instructions

The instruction is the most consequential part of any node. A vague instruction produces inconsistent results. A specific one produces reliable output.

Every instruction should cover three things:

1. What data or entities to look at.
2. What conditions or thresholds matter.
3. What the output should include and how it should be formatted.

### Weak vs. strong instructions

| Weak                                 | Strong                                                                                                                                                                                                                                                                                                     |
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "Fetch open issues from the tracker" | "Fetch all issues labeled 'urgent' created in the last 14 days. Exclude issues with status 'Closed' or 'Duplicate'. Group by assignee. For each assignee include: issue ID, title, creation date, and current status. Sort each group by creation date descending."                                        |
| "Analyze the data for trends"        | "Compare this period's metrics against the prior period. Flag any category where the value changed by more than 20%. For flagged categories, note whether it is an increase or decrease and compute the exact percentage change. If no category exceeds the threshold, state that all metrics are stable." |
| "Search the web for competitor info" | "Search for recent press releases and news articles about \[competitor] from the past 30 days. Focus on product launches, partnerships, and pricing changes. Organize findings by topic with source URLs."                                                                                                 |

### What makes an instruction strong

* Include time ranges, status filters, and exclusions so the node knows exactly what to include and what to ignore.
* Specify how results should be grouped and sorted.
* Name the exact output fields or columns you need.
* Specify what to output when there is no data or nothing to flag — otherwise, the node will decide on its own.

### Node-specific rules for Visual Mode

Each node's instruction must make sense on its own. Do not reference other nodes by name. Describe the input data the node should expect instead: *Given the list of assignees from the incoming issues, fetch their last 10 resolved tickets*.

Tell each node what to produce, not how to produce it. The node decides the implementation.

| Procedural (avoid)                                                                         | Outcome-focused (preferred)                                          |
| ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
| "SELECT \* FROM bugs WHERE severity = 'critical' AND created\_at > NOW() - INTERVAL 7 DAY" | "Fetch all critical bugs from the last 7 days, grouped by component" |
| "Use the EVALUATE\_CRITERIA tool to check if error count exceeds threshold"                | "Check if the total number of errors exceeds 10"                     |

Assign one responsibility per node. If an instruction covers two unrelated concerns, split it into two nodes.

## Writing trigger criteria

Trigger criteria determine when your agent acts versus staying silent. Vague criteria produce unpredictable behavior. Concrete thresholds produce consistent ones.

| Vague                   | Concrete                                                                                           |
| ----------------------- | -------------------------------------------------------------------------------------------------- |
| "If sales are low"      | "If daily revenue drops by more than 10% compared to the previous 7-day average"                   |
| "If there are problems" | "If the error rate exceeds 5% or if any orders are stuck in pending status for more than 48 hours" |
| "If something changed"  | "If revenue falls outside the 4% monthly variance range"                                           |

Start with a single condition. Once you confirm it fires correctly, add more. A multi-condition trigger that has never been tested independently is significantly harder to debug.

### When to use trigger criteria

Use trigger criteria when you only want output on specific conditions: anomaly detection, threshold breaches, or service level agreement violations. Leave the criteria field empty for regular reporting, such as daily summaries, weekly performance reviews, and monthly trend analysis, so the agent always delivers output when it runs.

## Choosing the right schedule

Match the schedule to how often your data changes and how quickly you need to act on it.

| Frequency | When to use                                                                                             | Examples                                              |
| --------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| Hourly    | Urgent, real-time monitoring only                                                                       | Production error rate spikes, critical SLA breaches   |
| Daily     | Most agents (recommended default)                                                                       | Sales metrics, pipeline health, support ticket volume |
| Weekly    | Trend analysis and summaries                                                                            | Week-over-week performance, team productivity         |
| Monthly   | High-level reviews and strategic reporting                                                              | Monthly business review, budget tracking              |
| Custom    | Define a cron expression (minute, hour, day, month, weekday) for schedules the preset tabs don't cover. |                                                       |

A daily schedule is the right default for most agents. Hourly runs add noise and make triggers harder to tune unless you genuinely need to react within the hour.

## Formatting output

Telling the agent what to analyze without telling it how to present results produces inconsistent outputs. Be explicit about structure in every instruction that generates an output.

* Name your section headings: "Section 1: Overview", "Section 2: Details"
* Specify table columns: "Include columns: Deal Name, Stage, Days Stuck, Owner"
* Define number formats: "Show currency as \$X,XXX" and "Show percentages as X.X%"
* Handle conditional sections: "Only include the Incidents section if incidents occurred"
* Set volume limits: "Limit to top 10 entries ranked by largest change"

Always state what the output should say when there is nothing to report. If you don't, the agent will generate something on its own, and it may not match what you expect.

## Routing data through If/Else nodes

If data is needed on both sides of an If/Else node, connect it through the node. Do not wire around it. Bypassing the node causes both branches to activate regardless of which condition is met.

Use concrete values in every If/Else condition.

| Vague                   | Concrete                                                          |
| ----------------------- | ----------------------------------------------------------------- |
| "There are many errors" | "The total count of items with status 'error' is greater than 10" |
| "Performance is poor"   | "The average response time exceeds 500ms"                         |

## Using the Artifact Builder

Connect Data and Analysis nodes directly to the Artifact Builder when the output requires tables or charts. Routing everything through a Summary node first strips the structured data the Artifact Builder needs.

Split the Artifact Builder instruction into two parts:

1. **Organization:** How to group the data, which tables or lists to create, and what to include in each section.
2. **Format:** How the final output should look: section headings, column names, number formats, and conditional sections.

## Testing before activating

Run a preview before publishing any agent. Click **Preview** at any point during building, not just when the workflow is complete, to check what each node is producing and catch problems before they compound.

### Iterating on results

| Problem                    | Fix                                                             |
| -------------------------- | --------------------------------------------------------------- |
| Output is too broad        | Add filtering criteria and exclusions to the instruction        |
| Data is missing            | Name the specific fields or columns you need                    |
| Formatting is inconsistent | Add explicit section headings, column names, and number formats |
| Trigger fires too often    | Tighten the threshold value                                     |
| Trigger never fires        | Loosen the threshold value                                      |

## Pre-publishing checklist

Before publishing any agent, confirm the following:

* Instruction covers what to analyze, what conditions matter, and how to format the output.
* Edge cases handled: output defined for when there is no data or nothing to flag.
* Trigger criteria use concrete values (if applicable).
* Trigger tested independently before full workflow test.
* Schedule matches how often the data changes.
* Output format specifies sections, columns, and number formats.
* Full end-to-end preview completed and output reviewed.
* Delivery channel configured.

## Next steps

<CardGroup>
  <Card title="Build an Agent in Visual Mode" icon="diagram-project" href="/setting-up-wisdom-ai/agents/visual-mode">
    Step-by-step guide to building your first Visual Mode agent.
  </Card>

  <Card title="Nodes Reference" icon="grid" href="/setting-up-wisdom-ai/agents/nodes-reference">
    Full description of every node type, its inputs, and when to use it.
  </Card>
</CardGroup>


# Agents Overview
Source: https://docs.wisdom.ai/setting-up-wisdom-ai/agents/agents



Agents are automated workflows that perform intelligent analysis autonomously. Think of an agent as a digital worker you configure once and leave running: it takes on a goal you define, pulls the data it needs from your domain context, runs the analysis, and delivers the result, without waiting for you to ask.

<Frame>
  <img alt="Agent configuration screen in WisdomAI showing Visual Mode canvas" />
</Frame>

An agent can:

* **Monitor your data** continuously and alert you the moment a metric crosses a threshold.
* **Run recurring analyses** on a fixed cadence, from daily summaries to weekly reports.
* **Explain what changed** by breaking down the drivers behind a shift, not just flagging that one occurred.
* **Deliver scheduled reports** via email or Slack.

<Note>
  WisdomAI offers two ways to build an agent:

  * **Prompt Mode**, where you describe what you want, and the agent figures out the steps on every run
  * **Visual Mode**, where the AI Builder generates a visual plan from your description that you review, freeze, and reuse on every run.

  Both are introduced in detail in the [Get started](#get-started) section at the end of this article.
</Note>

## Why use an agent

Beyond saving time, agents work at every scale, offering solutions from a single quick task to a full production workflow.

* **Simple to create, capable of complex work:** You describe the goal in a sentence, and the agent does the kind of multi-step work that would otherwise take hours. In Prompt Mode, a one-sentence description creates an agent. In Visual Mode, the WisdomAI Builder turns a plain-language description into a multi-step workflow. The agent then handles the hard parts on your behalf: querying the right data sources, comparing results across time periods, applying conditional logic, generating natural-language summaries, and delivering the output through the right channel.
* **Agency when you want it, determinism when you need it:**  Some work is best handled by letting the agent figure out the right approach as it runs. Other work needs to produce the same result every run. Prompt Mode builds a fresh plan each time the agent runs, leaving room for the LLM to explore and adapt. Visual Mode follows a plan you reviewed and locked in once, so the same inputs produce the same outputs every time. Pick the mode that fits the work.
* **Personal workflows and production workflows:**  Agents work for one-off personal monitoring as well as shared, recurring production reports. Spin up a Prompt Mode agent in a minute to keep an eye on your own metrics. Build a Visual Mode workflow when other people depend on the result, and consistency matters. The same platform handles both ends.

## When to use an agent

Reach for an agent when work needs to happen on its own, when you want analysis delivered without you having to run it, alerts raised without you having to watch, and reports produced without you having to remember.

### Common use cases

The first three examples below show how agents can build on one another within a single scenario, escalating from a simple alert to a full root cause investigation.

<Steps>
  <Step title="Monitor for problems">
    Use an agent to watch a metric and alert you only when something goes wrong.

    * **Trigger:** Sales fall below \$100,000 in the last day.
    * **Work:** Send a list of lost deals from the last day, including region, owner, and total value.

    A sales manager is alerted only when performance dips — no daily report to check, no threshold to remember.
  </Step>

  <Step title="Track significant changes">
    Use an agent to detect meaningful fluctuations in either direction, then explain what drove them.

    * **Trigger:** Daily sales move outside a 10% range compared to the same day last week.
    * **Work:** Compare today's lost and won deals against last week's, segment the difference by region, deal size, and sales rep, and surface the segments contributing most to the change.

    The alert from the previous step becomes a starting point for action.
  </Step>

  <Step title="Root-cause analysis">
    Use an agent to investigate why a metric changed, not just that it changed.

    * **Trigger:** Daily sales drop more than 15% week-over-week.
    * **Work:** Cross-reference the lost deals with recent product changes, support tickets from those accounts, sales rep activity logs, and pipeline movement to surface the most likely root causes.

    The segmentation from the previous step is now connected to other systems to produce a working hypothesis, not just a breakdown.
  </Step>
</Steps>

The steps above show how agents handle one scenario in depth. Agents also fit a wide range of recurring patterns, both reactive and proactive. Here are some typical examples.

| Use Case                          | Example                                                                                                                                                            | Best mode |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- |
| **Pipeline check**                | Flag deals stuck in the same stage for 7+ days, post to Slack each morning.                                                                                        | Prompt    |
| **Anomaly monitoring**            | If DAU drops 15% vs the 7-day average, post to a channel with context on what drove it.                                                                            | Prompt    |
| **Team summary**                  | Summarise this week's support tickets — volume, top categories, resolution trends — and email it Friday.                                                           | Prompt    |
| **Scheduled report**              | Pull last week's product usage by customer tier and email a summary of the biggest movers to the customer success team every Monday.                               | Both      |
| **Multi-source exec report**      | Pull revenue, pipeline, and support data from three sources, include an incidents section only if P0/P1s occurred, format as a branded PDF, deliver Monday at 7am. | Visual    |
| **Tiered alerting**               | Monitor app performance, billing, and support, route to different channels depending on which combination of signals fires.                                        | Visual    |
| **Personalised reports at scale** | Generate weekly performance reports for 50 regional managers, each filtered to their region.                                                                       | Visual    |

## Get started

WisdomAI offers two ways to build an agent. Choose the one that fits how you work.

### [Prompt Mode](/setting-up-wisdom-ai/agents/tutorial-create-agent)

Prompt Mode is the fastest way to get started. You write a plain-language description of what the agent should do when it runs, test it, and the agent is ready. This mode works well for **straightforward monitoring tasks**, such as tracking a metric, flagging a threshold, or sending a weekly summary.

### [Visual Mode](/setting-up-wisdom-ai/agents/visual-mode)

Visual Mode gives your agent a high-level plan to follow. Describe what you want in plain language, and the **WisdomAI Builder** generates the plan as a visual workflow of connected nodes — fetching data, running analysis, applying conditions, and delivering the result. You review the plan, refine it on the canvas if needed, and freeze it.

On every run, the agent refers back to this locked plan. Because the plan is explicit, execution stays consistent across runs, and you can model far more complex workflows than a single prompt could express. That makes Visual Mode the right choice for production workflows where both consistency and complexity matter.

You can also call on the Builder again at any point to modify an existing workflow, for example, to add a step, change a condition, or swap a data source.

### Create agent from chat

When you ask a chat question that implies a recurring need ("every Monday," "alert me when…"), Wisdom shows this prompt beneath the answer. Click **Create Agent** to open the agent builder with your question already filled in, then set a schedule and delivery channel.

<img alt="Image showing recurring agent in chat" />

## Next steps

<CardGroup>
  <Card title="Create an Agent" icon="robot" href="/setting-up-wisdom-ai/agents/tutorial-create-agent">
    Learn the basics of setting up a new AI agent for your data.
  </Card>

  <Card title="Build an Agent in Visual Mode" icon="diagram-project" href="/setting-up-wisdom-ai/agents/visual-mode">
    Step-by-step guide to building your first Visual Mode agent.
  </Card>
</CardGroup>


# Manage your Agents
Source: https://docs.wisdom.ai/setting-up-wisdom-ai/agents/manage-agents



After an Agent is created, it appears in a list on the main **Agents** page. From this page, you can manage all the Agents you have access to.

<img alt="Snippet showing the options to manage an agent" />

<img alt="Snippet showing the options to manage an agent" />

To manage an individual agent, locate it in the list and click the **three-dot menu (...)** under the **Actions** column. A dropdown menu will appear with the following options:

* **Trigger agent**: Manually runs the Agent’s entire workflow. The Agent will evaluate its trigger (if enabled) and, if the conditions are met (or if the trigger is disabled), run the full analysis and send a notification.
  Once you get the notification, you will be able to:
  * **View in WisdomAI**: it takes you to the chat window.
  * **View Agent**: it takes you to the agent configuration page.

<img alt="Snippet showing the email notification when the agent performs the analysis" />

* **Enable agent / Disable agent**: Toggles the agent between the **Active** and **Inactive** states. Disabling an agent stops it from running on its schedule; enabling it resumes normal runs and notifications. See [Agent states](#agent-states) below.
* **Edit agent**: Opens the canvas for Visual agents, allowing you to modify the Agent's name, trigger, work description, or schedule.
* **Share**: Allows you to share the Agent with other users for collaboration.
  * **Manage access**: grant **Editor** or **Viewer** access for that agent.
  * **Manage general access**: share it with everyone in your organization.
    <img alt="Snippet showing the share modal" title="2025-08-27_09-20-17.png" />
* **Duplicate agent**: Creates a copy of the agent that you can edit independently, without affecting the original.
* **Move to debug**: Switches the agent to the **Debug** state. The agent still runs on its schedule and produces output, but doesn't send notifications to subscribers. Use this to validate changes against live data without alerting your team.
* **Delete**: Permanently removes the Agent. This action cannot be undone.

## View previous Runs

You can view a detailed history of every time an agent has run. This log is useful for auditing and debugging an agent's behavior over time.

1. To see the log, find your agent on the **Agents** page and click the **Previous Runs** link in its corresponding row.
2. This will take you to the **Previous Runs** page, which displays a timeline of all past executions. Each entry in the log shows the status of the agent's key stages:

| **Stage**        | **Description**                                                           |
| :--------------- | :------------------------------------------------------------------------ |
| **WAKE UP**      | Confirms the agent started at its scheduled time.                         |
| **EVALUATION**   | Shows whether the trigger criteria were met.                              |
| **ANALYSIS**     | Confirms if the analysis was completed successfully.                      |
| **NOTIFICATION** | Shows if the notification was sent successfully or if there was an error. |

**Visual Agents** log each run per node. You can replay any run on the canvas to review the status of each node.

<img alt="Snippet showing rusn log per node" />

<img alt="Snippet showing rusn log per node" />

3. If an analysis was successfully generated, you can click the **View Conversation** button within the ANALYSIS step. This will take you to the specific conversation where you can inspect the detailed results and the exact query that was run for that execution.

<img alt="Gif showing the Previous Runs" />

## RBAC

Use Role-Based Access Control (RBAC) to manage collaboration. Refer to the table below to understand the differences between Editor and Viewer permissions and how they respect existing data access rules.

| Feature                  | Editor | Viewer |
| :----------------------- | :----: | :----: |
| View Agent & Run History |    ✅   |    ✅   |
| Edit Configuration       |    ✅   |    ❌   |
| Trigger/Test Runs        |    ✅   |    ❌   |
| Delete Agent             |    ✅   |    ❌   |

## Agent states

Every agent is always in one of three states, shown next to its name on the Agents page:

* **Active**: The agent runs normally and delivers notifications to its configured channel.
* **Inactive**: The agent doesn't run at all, scheduled or otherwise.
* **Debug**: The agent still runs on its schedule and produces output, but doesn't notify subscribers. Use this state to validate changes against live data without alerting your team.

### Changing an agent's state

From the agent's three-dot menu, you can select **Enable agent**, **Disable agent**, or **Move to debug** to change its state:

* An agent can only be moved to **Debug** from the **Inactive** state. Otherwise, **Move to debug** is greyed out.
* **Trigger agent** is also disabled while the agent is **Inactive**.

<img alt="GIF showing the agent status" />

## Reports

Each agent has a **Reports** list of its generated artifacts, with an **Export to PDF** action. (DOCX export is available via the API.)

To view an agent's reports:

1. On the **Agents** page, find the **Reports** column. Agents that have generated at least one report show an icon there, agents with no runs yet show none.
2. Click the icon to open that agent's Reports list.

<Frame>
  <img alt="Agent Reports Column" />
</Frame>

3. Each row shows the report name and the date and time it ran, along with its **Delivery** method and **Channel or Recipient**.
4. Click the **three-dot menu** next to a report to:
   * **Share Link**: Copy a shareable link to that report.
   * **Export to PDF**: Download the report as a PDF.

<Frame>
  <img alt="Agent Reports List" />
</Frame>

## Next steps

<CardGroup>
  <Card title="Connect to Slack" icon="slack" href="/integrations/connect-to-slack">
    Set up the Slack integration to receive notifications from your agents and stories.
  </Card>

  <Card title="Use Deep Analysis" icon="magnifying-glass-chart" href="/advanced-features/deep-analysis">
    Perform in-depth investigations for complex questions and receive a detailed report.
  </Card>
</CardGroup>


# Nodes Reference
Source: https://docs.wisdom.ai/setting-up-wisdom-ai/agents/nodes-reference



Nodes are the building blocks of a [Visual Mode agent](/setting-up-wisdom-ai/agents/visual-mode). Each node is a modular instruction that performs one focused task: fetching data, running analysis, applying a condition, or delivering a result.

<Note>
  **How nodes connect:** **Edges** connect nodes and define two things: the order of execution and the flow of data. Nodes connected in sequence run one after another. Nodes connected in parallel run at the same time. A node can only access data from the nodes that feed directly into it, but during execution, each node is automatically aware of the upstream context it depends on, so the workflow stays coherent end-to-end.
</Note>

This page describes every available node type, what it does, and when to use it.

## Trigger nodes

Trigger nodes are the entry point of every agent. Every workflow requires at least one trigger node, which determines when the agent runs. A workflow can include multiple schedule triggers, but only one manual trigger. Each schedule trigger can carry its own set of parameter values up to 25 per trigger.

The trigger node types are:

<AccordionGroup>
  <Accordion title="Manual trigger">
    Starts the agent when you run it manually from the Agent Builder canvas. Use this trigger during building and testing. The agent only executes when you initiate a run.

    **Trigger criteria (optional):** Enter a condition that must be true for the agent to proceed. If the condition is not met, the agent stops after the trigger node, and no downstream nodes execute. Leave empty to always proceed.
  </Accordion>

  <Accordion title="Schedule">
    Starts the agent on a recurring schedule you define. Use this trigger for production agents that need to run automatically: daily summaries, weekly reports, and real-time monitoring.

    **Trigger criteria (optional):** Same as Manual trigger. The agent evaluates the condition on each scheduled run and only proceeds if it is met.
  </Accordion>
</AccordionGroup>

<Note>
  External trigger is coming soon.
</Note>

## Data nodes

Data nodes bring information into the workflow. They are typically the first nodes connected after the trigger.

The data node types are:

<AccordionGroup>
  <Accordion title="Data">
    Fetches a structured dataframe from your connected data sources by executing SQL or Python against them. The dataframe is passed to downstream nodes with its schema intact: column names, types, and relationships are preserved throughout the workflow.

    **When to use:** Any time your agent needs to query your connected data: sales records, support tickets, usage metrics, and financial data.
  </Accordion>

  <Accordion title="Web Search">
    Searches the web and brings results into the workflow as context. Use this node when your agent needs information from outside your data lake: recent news, competitor activity, market events, or any external signal that your internal data does not capture.

    **When to use:** Correlation analysis (linking internal data spikes to external events), competitive monitoring, or any workflow that needs to reference current public information.
  </Accordion>

  <Accordion title="MCP Node">
    Calls an MCP (Model Context Protocol) tool to perform actions or retrieve data across connected surfaces. Use this node when your workflow needs to interact with an external system, such as creating a task, querying a third-party API, or triggering an action in a connected tool.

    **When to use:** Any workflow that needs to act on an external system rather than just read from your data lake.

    For setup, see [Connect an MCP server](/integrations/mcp-server/MCP-Server).
  </Accordion>
</AccordionGroup>

## Reasoning nodes

Reasoning nodes operate on dataframes and can take text or free-form inputs from other nodes to produce AI analysis. They analyse and summarise data to produce insights. Unlike Data nodes, Reasoning nodes do not query your databases — they work on data that has already been brought into the workflow by upstream nodes.

The reasoning node types are:

<AccordionGroup>
  <Accordion title="Analysis">
    Operates on a dataframe to derive new information by filtering, aggregating, ordering, scoring, enriching, or classifying rows. The output is a new or modified dataframe that can flow into further Reasoning nodes, an Artifact Builder, or a Control node.

    **When to use:** Any time you need to transform or analyze structured data before surfacing it: computing totals, flagging rows that meet a threshold, ranking results, or adding calculated fields.
  </Accordion>

  <Accordion title="Summary">
    Takes a dataframe or context as input and produces a textual narrative. Unlike Analysis, which outputs structured data, Summary outputs prose: a paragraph or set of sentences describing what the data shows.

    **When to use:** When your artifact needs a written interpretation of the data rather than (or in addition to) a table. Summary nodes work well feeding into an Artifact Builder alongside raw dataframes.
  </Accordion>
</AccordionGroup>

## Control nodes

Control nodes direct the flow of execution through the workflow. They evaluate conditions and determine which downstream nodes to run and which to skip.

The control node types are:

<AccordionGroup>
  <Accordion title="If/Else">
    Evaluates a condition against the data in the workflow and routes execution down one of two or more branches — the IF branch if the condition is true, the ELSE branch if it is not. Nodes on the inactive branch receive a no-op signal and are skipped entirely — they neither execute nor produce output.

    **When to use:** Any time your workflow needs to behave differently depending on what the data shows: sending an alert only when a threshold is breached, routing to different delivery channels based on a metric, or skipping delivery when there is nothing to report.

    **How data flows through If/Else:** The If/Else node is a gate, not a source of its own data. It passes whatever input it receives from upstream nodes through to the active branch — the data does not change, only the path it takes.

    If a downstream node needs data from before the If/Else node, route that data *through* the If/Else node. Do not wire around it. Bypassing the node causes both branches to activate regardless of which condition is met.
  </Accordion>
</AccordionGroup>

<Note>
  The Loop, Switch, and Human-in-the-Loop control node types are coming soon.
</Note>

## Artifact nodes

Artifact nodes format the workflow's output into a finished deliverable, ready for delivery.

The artifact node types are:

<AccordionGroup>
  <Accordion title="Artifact Builder">
    Ingests dataframes and context produced during the workflow run and formats them into a structured report. The Artifact Builder does not infer formatting — you define the structure explicitly in its instructions.

    Split your Artifact Builder instruction into two parts:

    * **Visual Organization:** How to group the data, which tables or lists to create, and what to include in each section.
    * **Format:** How the final output should look: section headings, column names, number formats, and conditional sections.

    **When to use:** Every agent that delivers a report, summary, or structured notification to an end recipient requires an Artifact Builder node. They are mandatory for every Agent.

    <Note>
      **Supported output formats:** Email with full table rows and fluid layout, Slack, PDF and DOCX.

      PPTX and XLSX are coming soon.
    </Note>

    <Note>
      Connect Data and Analysis nodes directly to the Artifact Builder when the output requires tables or charts. Routing everything through a Summary node first strips the structured data that the Artifact Builder needs.
    </Note>
  </Accordion>
</AccordionGroup>

## Delivery nodes

Delivery nodes send the artifact produced by the Artifact Builder to its destination. Every agent requires at least one delivery node to be published.

The delivery node types are:

<AccordionGroup>
  <Accordion title="Email">
    Sends the artifact to one or more email addresses. Supports full table rows at natural column widths, with no pagination or column truncation.
  </Accordion>

  <Accordion title="Slack">
    Posts the artifact to a Slack channel. Requires a Slack workspace connected to WisdomAI by a workspace administrator. See [Connect to Slack](/integrations/connect-to-slack).
  </Accordion>

  <Accordion title="Webhook">
    Sends the artifact to a webhook URL. Coming soon.
  </Accordion>
</AccordionGroup>

## Export nodes

Export nodes send a dataframe directly to external storage.

The export node types are:

<AccordionGroup>
  <Accordion title="Export">
    Exports one upstream dataframe to a connected S3 or Azure Blob Storage destination as a CSV file.

    **Setup:**

    1. Add the storage source: go to **Domains → Add source**, then select **S3** or **Azure Blob Storage**. The connection must have write access.
    2. In the Export node, select the **Destination** connection you added.
    3. Set a **file-path template** to define where the exported file is written and how it's named.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="Build an Agent in Visual Mode" icon="diagram-project" href="/setting-up-wisdom-ai/agents/visual-mode">
    Step-by-step guide to building your first Visual Mode agent.
  </Card>

  <Card title="Agent Best Practices" icon="star" href="/setting-up-wisdom-ai/agents/agent-best-practices">
    Learn how to write effective node instructions, triggers, and output formatting.
  </Card>
</CardGroup>


# Reviewed Runs in Agents
Source: https://docs.wisdom.ai/setting-up-wisdom-ai/agents/reviewed-runs-in-agents



Marking a run as a reference sets the standard for how your agent should behave, allowing the system to learn from its most successful outputs. When an agent execution meets your quality requirements, you can validate it to ensure consistency over time and prevent performance regressions. These historical examples provide the agent with a proven foundation to build on, replicating SQL patterns and formatting styles that already work.

This guide explains how to mark runs as reviewed, how the context injection works, and the benefits for your automated workflows.

## How it works

The process for using reviewed runs as a reference follows three main stages to ensure your agents maintain high standards over time.

<Steps>
  <Step title="Mark as Reviewed" icon="check">
    After an agent completes a successful run, navigate to the **Previous Runs** list. Click the **Mark as reviewed** button on the specific execution that produced the desired result.
  </Step>

  <Step title="Context Storage" icon="database">
    WisdomAI stores the full context of that validated run, including the specific steps taken, the generated SQL, and the exact output formatting used.
  </Step>

  <Step title="Reference Injection" icon="rotate-right">
    On future executions, WisdomAI automatically retrieves up to 3 of the most recently reviewed runs. These are injected as historical reference examples before the agent begins its new task, guiding it to follow the established logic and style.
  </Step>
</Steps>

<Frame>
  <img alt="Reviewed Run Agent" />
</Frame>

<Note>
  This feature acts as a regression guard, ensuring that once you have perfected an agent's behavior, that quality is preserved across future updates and similar queries.
</Note>

## Key capabilities

Reviewed runs provide the following technical advantages for maintaining agent performance:

* **Manual Validation:** Choose exactly which success-status runs to promote as references via the **Mark as reviewed** button.
* **Contextual Injection:** Automatically utilize up to 3 recently reviewed runs per execution for historical guidance.
* **Logic Consistency:** Improve the reliability of SQL patterns and tool call sequencing by providing a "gold standard" for the agent to follow.
* **Formatting Control:** Ensure the agent maintains a consistent output structure, which is critical for teams running recurring weekly or monthly reports.
* **Reversibility:** Remove the reviewed status at any time to update your reference library and ensure only the best examples are used.

<Frame>
  <img alt="Reviewed Run Agent Remove" />
</Frame>

## Target users

The reviewed runs feature is specifically designed for:

* **Agent owners & builders** who want to lock in high-quality performance once an agent run meets their exact requirements.
* **Data teams** that generate recurring weekly or monthly reports and need the output structure to remain identical across every execution.

## FAQs

<AccordionGroup>
  <Accordion title="Which runs can be marked as reviewed?">
    Only runs with a **Completed** status and an associated conversation can be marked as reviewed.
  </Accordion>

  <Accordion title="Can I unmark a run?">
    Yes. You can remove the reviewed status at any time. Once unmarked, that specific run will no longer be used as a reference for future agent tasks.
  </Accordion>

  <Accordion title="How many references are used at once?">
    WisdomAI uses up to the 3 most recent reviewed runs to provide context for a new execution.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="Create an Agent" icon="robot" href="/setting-up-wisdom-ai/agents/tutorial-create-agent">
    Learn the basics of setting up a new AI agent for your data.
  </Card>

  <Card title="Manage Your Agents" icon="list-check" href="/setting-up-wisdom-ai/agents/manage-agents">
    Explore how to monitor performance and view the Previous Runs list.
  </Card>
</CardGroup>


# Prompt Mode
Source: https://docs.wisdom.ai/setting-up-wisdom-ai/agents/tutorial-create-agent



Prompt Mode is the fastest way to build an agent in WisdomAI. Describe what you want the agent to do in plain language, test it, and the agent is ready. This tutorial walks through creating your first Prompt Mode agent end-to-end.

<Note>
  1. This guide uses sales-monitoring scenarios, but you can apply these steps to any metric you need to track.
  2. The Agents feature is currently in beta.
  3. If you need multi-step workflows with branching logic, see [Visual Mode](/setting-up-wisdom-ai/agents/visual-mode) instead.
</Note>

## Before you begin

Make sure you have the following:

* **Access to WisdomAI**: An active account with access to the **Agents** tab.
* **A connected domain**: A [domain](/setting-up-wisdom-ai/basic-tutorial-connect-and-test) connected to the data you want the agent to work with.
* **A delivery channel**: Email or Slack, ready to configure. To deliver to Slack, an administrator must first connect your Slack workspace to WisdomAI.
  <Note>
    See the [Slack](/integrations/connect-to-slack) guide for setup steps.
  </Note>

## Create an Agent

To create a new agent, follow these steps:

1. From the sidebar on the left, select the **Agents** tab.
2. If no agents have been configured, you will see a welcome screen. Click **Get started**.

<img alt="Screenshot showing the Get Started button" />

3. **Select an Agent**: In the **Create Agent** modal, select **Prompt Agent**. A prompt form opens.

<Note>
  Use the toggle in the top-right corner of the form to switch between **Prompt** and [**Visual**](/setting-up-wisdom-ai/agents/visual-mode) mode.

  <img alt="Screenshot showing Prompt mode" />
</Note>

4. **Agent Name**: Provide a descriptive name for your Agent to easily identify it later.
5. Configure the **Activation** **Trigger**. The optional trigger allows you to choose between two modes of operation: scheduled reporting or conditional monitoring.
   1. **Trigger Disabled (Scheduled Reporting)**: Leave the trigger disabled to use the Agent for scheduled reporting. In this mode, the analysis will always run and send out a notification according to the schedule you set.
   2. **Trigger Enabled (Conditional Monitoring)**: Enable the trigger to use the Agent as a monitor for specific conditions. In this mode, an analysis and notification are sent only if the trigger's conditions are satisfied.
      * In the text box, describe the condition. You can write complex criteria. For example: `If total sales in the last year fall below $100,000`.
      * Click **Test** to verify whether the condition is currently met based on your data.
        <Tip>
          Start with simple, single-condition triggers to ensure they work as expected before creating more complex ones.
        </Tip>

<img alt="Agent configuration screen with trigger enabled" />

6. Define the **Work Description**. This is the task the Agent will perform if the trigger condition is met.
   * In the work description text box, describe the analysis and action you want in natural language. For example: `Send me a list of all lost deals along with their region, their owner, and their total value`.
   * Click **Test** to run the analysis and see a sample of the output. This allows you to preview the results that will be sent in the notification.
7. Set the Schedule for the agent by selecting one of the following tabs. Every tab includes a time zone selector.
   * **Hourly**: Choose the run interval and the minute within the hour to run at.
   * **Daily**: Runs the agent every day at the time you specify.
   * **Weekly**: Choose which day(s) to run on. Select individual days, or use the Weekdays, Weekends, or Every day presets, then set the time.
   * **Monthly**: Choose a day of the month and a time. The agent runs on that day each month.
   * **Custom**: Define a cron expression (minute, hour, day, month, weekday) for schedules the preset tabs don't cover.
8. Configure **Notifications** to define how you will receive the analysis results.
   * **Email**: Select this option and enter one or more email addresses. The notification will contain charts and tables from the analysis.
   * **Slack**: Select this option and specify the Slack channel names.
9. Click **Create Agent** to save and activate it.

<img alt="Create Agent button to save and activate the agent" />

10. You will receive a notification alerting you that you have been subscribed to that Agent. From there, you can directly access it using the **View Agent** button. This is what an email notification looks like:

<img alt="2025-08-27_08-57-07.png" />

## Test an Agent during configuration

While creating or editing an Agent, you can test its two main components, the **Activation Trigger** and the **Work Description**, independently before saving. This helps you refine each part and ensure the Agent will behave as expected.

* **Test the Activation Trigger**: Below the trigger text box (visible only when the trigger is enabled), click **Test** to verify if your condition is currently met based on the data. This is useful for verifying that your natural language criteria are written correctly and will activate when you expect them to. The test will show you if the trigger would fire and why.
* **Test the Work Description**: Below the work description text box, click **Test** to run the analysis and preview the output. This allows you to see a sample of the report that the Agent will generate, so you can adjust the description to get the exact information you need in your notifications.

<img alt="Gif showing the Test button in action" />

## Use Deep Analysis with an Agent

You can have an Agent run its analysis using the Deep Analysis feature. When you enable Deep Analysis for an Agent, it performs a more thorough analysis by exploring multiple aspects of the data and providing comprehensive insights. Deep Analysis runs more thoroughly than a standard agent run, so it takes longer but produces more complete insights.

1. When creating or editing an Agent, enable the **Deep Analysis** toggle.
2. When the Agent runs, it will automatically generate and execute a multi-step analysis plan based on your work description. You will not be prompted to approve the plan; it will run automatically.

<Note>
  To learn more about this functionality, read the [Use the Deep Analysis Functionality](/advanced-features/deep-analysis) article.
</Note>

<img alt="Snippet showing the Deep Analysis toggle enabled" />

## Manage agent versions

Every edit publishes a new version of the agent. Versions give you a history of every change, so you can see what a past publish looked like or restore it if a newer change causes problems.

<img alt="Snippet showing the prompt versioning" />

## Next steps

<CardGroup>
  <Card title="Manage Your Agents" icon="sliders" href="/setting-up-wisdom-ai/agents/manage-agents">
    Explore how to test, edit, share, and view the run history of your existing agents.
  </Card>

  <Card title="Connect to Slack" icon="slack" href="/integrations/connect-to-slack">
    Set up the Slack integration to receive notifications from your agents and stories.
  </Card>
</CardGroup>


# Visual Mode
Source: https://docs.wisdom.ai/setting-up-wisdom-ai/agents/visual-mode



This guide walks through building an agent using Visual Mode in WisdomAI, from selecting a trigger to publishing your workflow for delivery. If you prefer to describe what you want and let the agent figure out the steps on every run, see [Create an agent - Prompt Mode](/setting-up-wisdom-ai/agents/tutorial-create-agent).

<Note>
  The Agents feature is currently in beta.
</Note>

## Before you begin

Make sure you have the following:

* **Access to WisdomAI**: An active account with access to the **Agents** tab.
* **A connected domain**: A [domain](/setting-up-wisdom-ai/basic-tutorial-connect-and-test) connected to the data you want the agent to work with.
* **A delivery channel**: Email or Slack, ready to configure. To deliver to Slack, an administrator must first connect your Slack workspace to WisdomAI. See [Connect to Slack](/integrations/connect-to-slack).

## What is Visual Mode

Visual Mode lets you build an agent as an explicit, node-based workflow on a canvas. You define each step: data, AI reasoning, artifact and delivery. The agent executes those exact steps on every run.

This differs from Prompt Mode, where the agent decides its own steps at runtime. Visual Mode trades that flexibility for repeatable, inspectable control: you can see exactly what the agent will do before it runs, and trust that it will do the same thing every time.

## Step 1: Open the Agent Builder

Click **Create Agent** to open a modal and pick **Prompt agent** or **Visual agent**. Choose Visual agent to open the canvas.

1. Navigate to the **Agents** tab in the left sidebar and click **Create Agent**.
   <Frame>
     <img alt="Create Agent Builder" />
   </Frame>
2. Select the **domain** your agent will run in.
   <Frame>
     <img alt="Select Domain" />
   </Frame>
3. (Optional) Edit your agent's name by clicking on the pencil icon. Add it in the **Agent Settings** modal and click **Save**.
   <Frame>
     <img alt="Setup Agent Name" />
   </Frame>

## Step 2: Generate your workflow with the WisdomAI Builder (recommended)

Rather than placing nodes manually, you can describe your agent in plain language and let the **WisdomAI Builder** generate the structure for you. The WisdomAI Builder is an AI-powered chat panel built into the canvas. Type what you want your agent to do in the **Describe your agent** bar at the bottom of the screen. WisdomAI Builder reads your connected domain and data sources, constructs the complete node structure, and renders it on the canvas for you to review, adjust, and publish.

<video />

You can use the WisdomAI Builder at any point, such as to create an agent from scratch or to modify an existing workflow. For example: *add a conditional branch that skips delivery if revenue is above target.*

<Frame>
  <img alt="Add Node To Agent" />
</Frame>

If you prefer to place and configure nodes yourself, or want to refine what the Builder generated, continue to Step 3.

## Step 3: Build manually

Use manual building when you want to refine the workflow the Builder generated — swap a data source, add a condition, change an instruction — or when you prefer to place and configure each node yourself. You can build manually from the start or at any time after the Builder generates your workflow.

Every agent starts with a trigger node, which defines when the agent runs.

1. Click the trigger node on the canvas. The **Select trigger** panel opens on the right.
2. Choose a trigger type.

| Trigger            | When to use                                              |
| ------------------ | -------------------------------------------------------- |
| **Manual trigger** | Use this when you need this analysis to run on demand.   |
| **Schedule**       | Use this when you want a recurring analysis on schedule. |

3. If you select the Schedule trigger and want it to act only when a condition is met, enter it in the **Trigger Criteria** field. Leave it empty to run unconditionally every time the trigger fires.
   <Tip>
     Start with a single condition. Once you confirm it fires correctly, add more. Debugging a multi-condition trigger from scratch is significantly harder than layering conditions one at a time.
   </Tip>
   Here, also define when the agent runs: **Hourly**, **Daily**, **Weekly**, **Monthly**, or **Custom**. Match the frequency to how often your data changes and how quickly you need to act on it.
4. Click **Done**.

<Frame>
  <img alt="Select Trigger" />
</Frame>

### Add and connect nodes

Nodes are the building blocks of a Visual Mode agent. Each node performs a specific task. They are connected through Edges, and these also define both the order of execution and how data flows between them.

<Note>
  For a full description of node types and how they behave, see the [Nodes Reference](/setting-up-wisdom-ai/agents/nodes-reference).
</Note>

To add a node:

1. Click the **+** button on the trigger node to open the **Add node** menu.
2. Select the node type you want to add.

<Frame>
  <img alt="Add node snippet" />
</Frame>

3. Click on it to write an instruction in the node's settings panel describing what it should do with its input.
4. Click **Done**.
   <Frame>
     <img alt="Snippet showing how instructions are written for the node" />
   </Frame>
5. To add another node, click the circular button on any node's output and extend the arrow to add the next node in the flow. Repeat until your workflow is complete.

<Tip>
  You don't have to finish the entire workflow before testing. Click **Preview** at any point to run the agent to its current state and see what each node produces. This makes it easier to catch problems early, before adding more nodes on top.

  <video />
</Tip>

<Warning>
  When you hover the mouse over a node, the **Delete node** icon appears. Click on it. In the modal that opens, select **Delete** to confirm the operation. **This action is irreversible**.

  <Frame>
    <img alt="Delete a node modal" />
  </Frame>
</Warning>

## Step 4: Configure the Artifact Builder

The Artifact Builder formats your workflow's output into a finished report for delivery.

1. Add the **Artifact Builder** node to the canvas, then click it to open its settings.
2. Write an instruction that covers two things separately: how to organize the data into sections, lists, and tables; and how to format the final output: headings, number formats, and layout.

Be explicit about formatting. The Artifact Builder does not infer structure on its own. Include details like:

* Section headings: "Section 1: Overview", "Section 2: Details"
* Table columns: "Include columns: Deal Name, Stage, Days Stuck, Owner"
* Number formats: "Show currency as \$X,XXX" and "Show percentages as X.X%"
* Conditional sections: "Only include the Incidents section if incidents occurred."

3. Click **Done**.

<video />

<Note>
  Every agent requires at least one Artifact Builder node and one delivery node before it can be published.
</Note>

## Step 5: Configure delivery

The delivery node sends your artifact to its destination.

1. Click **+** after the Artifact Builder node and select **Email** or **Slack**
2. Enter the destination: an email address or Slack channel name.
3. Click **Done**.
   <Frame>
     <img alt="Agent Email Node" />
   </Frame>

<Note>
  To deliver to Slack, a workspace administrator must first connect your Slack workspace to WisdomAI. See [Connect to Slack](/integrations/connect-to-slack).
</Note>

## Step 6: Preview and test

At any point before publishing, you can run the agent manually to verify that the output is correct. To do this:

1. Click **Preview** in the top right corner.
2. You don't have to wait for the run to finish. As the agent executes, watch the canvas for progress. A green check confirms a node succeeded, a red X indicates a failure. Click the node to see the error.
3. At any point during or after the run, click on a node to review the data generated, the analysis performed, and the underlying SQL or Python code used.
   <Frame>
     <img alt="Snippet showing the data fetched by the node" />
   </Frame>
4. Click **End Preview** to return to the edit mode and adjust node instructions, trigger criteria, or formatting as needed, then preview again.

### Common fixes

| Problem                    | Fix                                                                                |
| -------------------------- | ---------------------------------------------------------------------------------- |
| Output is too broad        | Add filtering criteria and exclusions to the instruction                           |
| Data is missing            | Name the specific fields or columns you need                                       |
| Formatting is inconsistent | Add explicit section headings, column names, and number formats to the instruction |
| Trigger fires too often    | Tighten the threshold value                                                        |
| Trigger never fires        | Loosen the threshold value                                                         |

## Step 7: Publish your Agent

Once the preview output looks correct, make the agent live. To do that, click the **Publish** button. Your agent will become active instantly.

<Frame>
  <img alt="Image showing the publish Agent button in the UI" />
</Frame>

The agent will run on the schedule you configured (unless you have chosen the manual trigger) and deliver output to the method you set. You can monitor past runs, edit the agent, or adjust the schedule at any time from the **Agents** tab.

<Note>
  Publishing also saves the agent's current configuration as a new version. See Manage agent versions below to view, compare, or revert to a previous version.
</Note>

## Step 8: Manage agent versions

Every Publish creates a new version of the agent. Versions give you a history of every change, so you can see what a past publish looked like or restore it if a newer change causes problems.

<img alt="Snippet showing the versioning" />

## Next steps

<CardGroup>
  <Card title="Manage your Agents" icon="sliders" href="/setting-up-wisdom-ai/agents/manage-agents">
    Learn how to edit, share, and view the run history of your agents.
  </Card>

  <Card title="Nodes Reference" icon="grid" href="/setting-up-wisdom-ai/agents/nodes-reference">
    Explore the full list of node types, inputs, and outputs.
  </Card>
</CardGroup>


# Basic Tutorial: Connect and Test
Source: https://docs.wisdom.ai/setting-up-wisdom-ai/basic-tutorial-connect-and-test



This tutorial is intended for Admin users who are responsible for configuring data sources and setting up WisdomAI.

## Learning objectives

By the end of this tutorial, you will be able to:

* Connect to your Database.
* Start querying your data to test WisdomAI.
* Provide feedback so the system can refine its context based on your input.

Once you have completed this tutorial, you will have WisdomAI connected to your data and ready to improve through real-time interaction and feedback.

## Before you begin

To follow this tutorial, you should:

* Have Admin access to your WisdomAI account.
* Know the credentials to access your data source.

## 1. Connect to data sources

To get started, you first need to connect your existing data source to WisdomAI so the system can access and prepare your data for use and create reports:

1. Go to the left sidebar and select **Connections**.
2. Click on the **Add Connection** button to start.
   <Note>
     This action lets you link your existing data sources to WisdomAI. Doing so enables the system to scan metadata. For data warehouse connections, it also enables WisdomAI to fetch data when users ask natural-language questions.
   </Note>

<Frame>
  <img alt="Connections and Add Connection screens with the nav item, Add connection button, and data source picker highlighted" />

  <img alt="Connections and Add Connection screens with the nav item, Add connection button, and data source picker highlighted" />
</Frame>

3. Select your data source type from the list (for example, Snowflake, BigQuery, PostgreSQL, or MCP Server).
   <Info>
     Access [Supported Data Sources](/getting-started/connect-data-sources/supported-data-sources) to see the complete list of supported data sources by WisdomAI.
   </Info>
4. Add a **Connection name** and fill in the connection details for your selected data source, such as account information, authentication method, and any relevant filters.
   <Note>
     The fields and authentication options shown depend on the data source you selected in step 3. See [Supported Data Sources](/getting-started/connect-data-sources/supported-data-sources) for source-specific setup guides.
   </Note>
5. Click on the **Save and Sync metadata** button.

<Frame>
  <img alt="Redshift Connection Details form with the credentials panel and Save and Sync metadata button highlighted" />

  <img alt="Redshift Connection Details form with the credentials panel and Save and Sync metadata button highlighted" />
</Frame>

<Warning>
  **Note on Syncing**: After successfully adding a connection, the initial sync may take a few minutes to complete. Then, data will be available for analysis.
</Warning>

## 2. Select the data

After you add your data source, select the data you want to use in your project. For this, you will need to create a Domain.

1. Go to **Domains** in the left sidebar.
   <Note>
     A Domain represents a logical business area or function, such as Sales, Marketing, or Finance. Creating well-defined domains makes data more accessible and relevant to business users.
   </Note>
2. Click on the **Add Domain** button. A new window will open.
3. Enter the **Domain name** and **select the data source** from the dropdown menu.
4. Click **Create Domain** to continue.

<Frame>
  <img alt="Domains list with the Add domain button highlighted, and the Create New Domain modal with domain name, data source selection, and Create Domain button highlighted" />

  <img alt="Domains list with the Add domain button highlighted, and the Create New Domain modal with domain name, data source selection, and Create Domain button highlighted" />
</Frame>

5. The next window will vary depending on what you selected in step 3:
   * If you selected an existing **Data source**, choose the **tables** you would like to use, then click **Add Table**.
   * If you selected **Add Files**, upload your CSV, TSV, PDF, Word, PowerPoint, or other files, then click **Upload**.
   * If you selected **Connect new Data store or MCP server**, configure the connection as prompted, then follow the applicable step to finish adding it (this varies by source type).
6. Click **Add Table** or the corresponding option (e.g., **Upload**), depending on your selection.

Once your data is added, you are ready to start querying it to retrieve information and generate reports about your business.

<Frame>
  <img alt="Add Data to Domain modal window displayed" />

  <img alt="Add Data to Domain modal window displayed" />
</Frame>

<Tip>
  If you want to connect a new source, select this option in step 3. In the same window, you can choose to connect a new Data store or MCP server, or add files (CSV, TSV, or Excel).

  <Frame>
    <img alt="Connect Data Surce step" />

    <img alt="Connect Data Surce step" />
  </Frame>
</Tip>

## 3. Upload CSV files (Optional)

In addition to database connections, Admins can add data directly to a Domain using CSV, TSV, or Excel files. When an Admin adds a file this way, the data becomes a permanent part of the Domain and is available to all users with access to that Domain.

1. Navigate to **Domains** in the left sidebar and select your Domain.
2. Go to the **Data Sources** tab.
3. Click **Add Table** and select **Create from CSV**.

<img alt="Domain screen showing the Upload a CSV file option" />

<img alt="Domain screen showing the Upload a CSV file option" />

4. Upload your file and configure the column types.

<img alt="Configure tables modal" />

<img alt="Configure tables modal" />

<Note>
  **Replace an Existing Table**

  You can also replace an existing CSV table instead of uploading a new one. This allows you to update the underlying data while preserving all existing column descriptions, settings, and domain configurations. To learn how to do it, see our [Work with CSV Files](/using-wisdom-ai-everyday/work-with-csv-files) guide.
</Note>

5. Click **Create table**.

<img alt="Create Table From Csv Domain02" />

<img alt="Create Table From Csv Domain02" />

<Tip>
  **Use CSVs as an Explorer**

  WisdomAI also allows non-admin users to create private domains or attach CSVs directly to a chat for quick analysis. For a full breakdown of these features and detailed configuration steps, see our [Work with CSV Files](/using-wisdom-ai-everyday/work-with-csv-files) guide.
</Tip>

## 4. Start testing

Once your data is set up and selected, you can start querying your data to see WisdomAI in action and test its data analysis capabilities. Here are some example questions you may ask:

* *"What was our revenue by region last quarter?"*
* *"Show me customer retention by month."*
* *"Which products had the highest growth rate compared to last year?"*

While experimenting with your AI data analyst, you can **train** it by providing **feedback**. There are three main ways to do so:

* Using the **thumbs up/down** icons. If your feedback was thumbs down, a new window opens so you can adjust the query accordingly. The more thumbs up/down you provide, the more you will train the tool to get high-quality, correct answers.
* By **changing the SQL Code**.
* By **Fine-tuning** the **Knowledge**.

<Info>
  Think about the following scenario: you tell the system that the Report it created is incorrect, so you provide the accurate data in the chat. If this additional context has not been added to the database tables, you can add it directly in the chat.
</Info>

In all these cases, the system will use the provided data to further refine the context of your database, enabling it to provide better answers in future searches, as shown in the example images below.

<img alt="Thumb Down Feedback" />

<img alt="Thumb Down Feedback" />

<img alt="Revenue By Region" />

<img alt="Revenue By Region" />

<Note>
  Currently, feedback icons (thumbs-up and thumbs-down) appear only for responses containing charts or structured data. Feedback for text-only responses is not yet supported, but will be available in a future update.
</Note>

## Next steps

<CardGroup>
  <Card title="Supported Data Sources" icon="database" href="/getting-started/connect-data-sources/supported-data-sources">
    Explore the full list of databases and platforms you can connect to the system.
  </Card>

  <Card title="Advanced Data Modeling" icon="sitemap" href="/setting-up-wisdom-ai/advanced-data-modeling-creating-context">
    Define relationships and context in your data to enable more powerful analysis.
  </Card>

  <Card title="Provide Feedback to the System" icon="thumbs-up" href="/setting-up-wisdom-ai/feedback-mechanisms/provide-feedback-to-the-system">
    Learn how to rate answers and provide corrections to improve the system's accuracy.
  </Card>
</CardGroup>

4. Upload your file and configure the column types.

<img alt="Configure tables modal" />

<img alt="Configure tables modal" />

<Note>
  **Replace an Existing Table**

  You can also replace an existing CSV table instead of uploading a new one. This allows you to update the underlying data while preserving all existing column descriptions, settings, and domain configurations. To learn how to do it, see our [Work with CSV Files](/using-wisdom-ai-everyday/work-with-csv-files) guide.
</Note>

5. Click **Create table**.

<img alt="Create Table From Csv Domain02" />

<img alt="Create Table From Csv Domain02" />

<Tip>
  **Use CSVs as an Explorer**

  WisdomAI also allows non-admin users to create private domains or attach CSVs directly to a chat for quick analysis. For a full breakdown of these features and detailed configuration steps, see our [Work with CSV Files](/using-wisdom-ai-everyday/work-with-csv-files) guide.
</Tip>

## Start testing

Once your data is set up and selected, you can begin experimenting with your WisdomAI chatbot to see it in action and test its data analysis capabilities. Here are some example questions you may ask:

* *"What was our revenue by region last quarter?"*
* *"Show me customer retention by month."*
* *"Which products had the highest growth rate compared to last year?"*

While experimenting with your chatbot, you can **train** it by providing **feedback**. There are three main ways to do so:

* Using the **thumbs up/down** icons. If your feedback was thumbs down, a new window opens so you can adjust the query accordingly. The more thumbs up/down you provide, the more you will train the tool to get high-quality, correct answers.
* By **changing the SQL Code**.
* By **Fine-tuning** the **Knowledge**.

<Info>
  Think about the following scenario: you tell the system that the Report it created is incorrect, so you provide the accurate data in the chat. If this additional context has not been added to the database tables, you can add it directly in the chat.
</Info>

In all these cases, the system will use the provided data to further refine the context of your database, enabling it to provide better answers in future searches, as shown in the example images below.

<img alt="Thumb Down Feedback" />

<img alt="Thumb Down Feedback" />

## 4. Start testing

Once your data is set up and selected, you can start querying your data to see WisdomAI in action and test its data analysis capabilities. Here are some example questions you may ask:

While experimenting with your AI data analyst, you can **train** it by providing **feedback**. There are three main ways to do so:

<img alt="Revenue By Region" />

<img alt="Revenue By Region" />


# Context Modeling Workflow
Source: https://docs.wisdom.ai/setting-up-wisdom-ai/context-modeling-guide-workflow



This guide outlines the complete, multi-step process for modeling your business Context in WisdomAI. The steps are:

1. [Build the foundation](#step-1-build-the-foundation-with-a-semantic-layer)
2. [Define complex Metrics](#step-2-define-complex-metrics-with-reviewed-queries)
3. [Refine and harden your logic](#step-3-refine-and-harden-your-logic)
4. [Test and measure your impact](#step-4-test-and-measure-your-impact)

The sections below describe each step of this workflow.

## Step 1: Build the foundation with a semantic layer

Before you can tackle complex analysis, you must establish a solid foundation. This involves creating a business-friendly semantic layer over your raw database structures and enriching it with basic, domain-specific language.

* **What you'll do**: Document tables and columns, define business entities, establish relationships, and add simple rules using natural language context.
* **How to do it**: For a detailed walkthrough, refer to our guide on [Advanced Data Modeling: Creating Context](/setting-up-wisdom-ai/advanced-data-modeling-creating-context).

## Step 2: Define complex Metrics with Reviewed Queries

For specific business calculations where an exact SQL structure is required, you should provide the AI with pre-vetted examples. This is ideal for complex metrics that might need window functions or nested queries.

* **What you'll do**: Create a library of **Reviewed Queries** by pairing a natural language question with its ideal SQL response.
* **How to do it**: The creation process is covered in our guide on [Advanced Data Modeling: Creating Context](/setting-up-wisdom-ai/advanced-data-modeling-creating-context).

## Step 3: Refine and harden your logic

Once your foundational context is in place, you can apply advanced strategies to make your logic more robust, maintainable, and accurate.

### Optimize your SQL for Reviewed Queries

The structure of your SQL has a significant impact on clarity and reusability. Follow these best practices to write more effective queries.

* **Use Common Table Expressions (CTEs) for clarity.** For complex logic, breaking the query into understandable CTEs makes it more readable and allows for reuse in future metrics.
* **Maintain consistent structures for related metrics.** When creating multiple variations of a metric, use a shared CTE to define the base calculation. This prevents logic from drifting between different reports.

### Combine Knowledge types for greater accuracy

In some complex cases, the AI might not follow an SQL example perfectly, leading to logical errors like double-counting. You can prevent this by supplementing your Validated Queries with explicit instructions in the Language Knowledge.

For example, if there is a pre-aggregated `country_population` column in a `statewise_population` table, adding `country_population` across states in the same country would lead to double-counting. An instruction might help to make sure this never happens; add a rule like: `"Never sum up country_population column across different rows for the same country"` to prevent incorrect aggregations.

## Step 4: Test and measure your impact

Knowledge modeling is an iterative process. To validate your improvements and track accuracy over time, you must continuously test your setup using a dedicated evaluation framework.

* **What you'll do**: Create **Evaluation Sets** containing test prompts and their expected SQL outputs, run evaluations, and analyze the reports to identify areas for improvement.
* **How to do it**: Learn the complete testing workflow in our guide, [Use Evaluations Sets and Runs](/improve-wisdom-ai-responses/use-evaluations-sets-and-runs).

## Next steps

<CardGroup>
  <Card title="Auditing" icon="clipboard-list" href="/using-wisdom-ai-everyday/auditing">
    Review query history and system activity to ensure compliance and accuracy.
  </Card>

  <Card title="Provide Feedback to the System" icon="thumbs-up" href="/setting-up-wisdom-ai/feedback-mechanisms/provide-feedback-to-the-system">
    Learn how to rate answers and provide corrections to improve the system's accuracy.
  </Card>

  <Card title="Validate and Test Answers" icon="check-double" href="/improve-wisdom-ai-responses/validate-and-test-answers">
    Understand the methods for verifying the correctness and reliability of generated answers.
  </Card>
</CardGroup>


# Limited Context
Source: https://docs.wisdom.ai/setting-up-wisdom-ai/feedback-mechanisms/limited-context



The **Has Limited Context** marker is a key signal for monitoring the quality of WisdomAI responses. If the system lacked complete domain context to answer a question confidently, it forced the Large Language Model (LLM) to make assumptions based on partial information. These responses may still be helpful but require closer review to ensure accuracy.

Administrators are responsible for identifying and acting upon Limited context markers to maintain the precision of the domain configuration. You can find this filter in the **Chat Log**.

<img alt="Image showing the Has Limited Context switch" />

<img alt="Image showing the Has Limited Context switch" />

Limited context markers are displayed next to generated visualizations or answers. Click **Chat Details** to see more information, then click **Open in Chat** to view the full conversation.

<Frame>
  <img alt="Limited Context Marker" />
</Frame>

<Warning>
  Repeated Limited Context markers on similar topics may indicate missing concepts in the knowledge base. Consider updating domain content to reduce future uncertainty and improve overall response quality.
</Warning>

## Next steps

<CardGroup>
  <Card title="Turn Answers into Dashboards" icon="book-open" href="/using-wisdom-ai-everyday/turn-answers-into-dashboards">
    Compile key insights and visualizations into a shareable, narrative-driven report.
  </Card>

  <Card title="Monitor Negative Feedback" icon="thumbs-down" href="/setting-up-wisdom-ai/feedback-mechanisms/monitor-negative-feedback">
    Track and analyze negative user feedback to identify areas for system improvement.
  </Card>

  <Card title="Provide Feedback to the System" icon="thumbs-up" href="/setting-up-wisdom-ai/feedback-mechanisms/provide-feedback-to-the-system">
    Learn how to rate answers and provide corrections to improve the system's accuracy.
  </Card>
</CardGroup>


# Monitor Negative Feedback
Source: https://docs.wisdom.ai/setting-up-wisdom-ai/feedback-mechanisms/monitor-negative-feedback



Administrators are responsible for reviewing and acting upon the negative feedback provided by all users. View a list of responses with negative feedback by navigating to the **Chat Log** tab within the WisdomAI interface and switching the **Has Negative Feedback** toggle.

<img alt="Chat Log tab with the Has Negative Feedback toggle on" title="Negative Feedback Chat Log Pn" />

<img alt="Chat Log tab with the Has Negative Feedback toggle on" title="Negative Feedback Chat Log Pn" />

## Get email notifications

The system automatically channels negative feedback to administrators via email, ensuring prompt attention to issues that require intervention.

<img alt="Image of a Feedback Email For Admins" title="Feedback Email For Admins Pn" />

<Info>
  This is a Beta feature, reach out to support at [support@askwisdom.ai](mailto:support@askwisdom.ai) to sign up for email notifications when negative feedback is submitted.
</Info>

## Best practices when you see negative feedback

1. If the issue is just an incorrect SQL, you can [edit the response](/improve-wisdom-ai-responses/validate-and-test-answers#1-edit-the-sql-query).
2. If it is an understanding gap, which is generally applicable, then you should [add knowledge to your Domain](/improve-wisdom-ai-responses/validate-and-test-answers#3-add-context-knowledge).
3. If this is some kind of feedback on the WisdomAI product, contact [support@askwisdom.ai](mailto:support@askwisdom.ai).

<Note>
  For Domains with high usage or complex data, we recommend you to assign a dedicated administrator to regularly review feedback and make all the necessary updates to the knowledge base, ensuring continuous optimal performance.
</Note>

## Next steps

<CardGroup>
  <Card title="Turn Answers into Dashboards" icon="book-open" href="/using-wisdom-ai-everyday/turn-answers-into-dashboards">
    Compile key insights and visualizations into a shareable, narrative-driven report.
  </Card>

  <Card title="Limited Knowledge" icon="puzzle-piece" href="/setting-up-wisdom-ai/feedback-mechanisms/limited-context">
    Understand how to identify and flag when the system's answers lack necessary context.
  </Card>

  <Card title="Provide Feedback to the System" icon="thumbs-up" href="/setting-up-wisdom-ai/feedback-mechanisms/provide-feedback-to-the-system">
    Learn how to rate answers and provide corrections to improve the system's accuracy.
  </Card>
</CardGroup>


# Provide Feedback to the System
Source: https://docs.wisdom.ai/setting-up-wisdom-ai/feedback-mechanisms/provide-feedback-to-the-system



Your feedback is essential for improving WisdomAI's accuracy and reliability. By rating answers and providing corrections, you help the system learn and refine its responses. This guide walks you through the feedback process for all users.

* [Rate an answer](#1-rate-an-answer)
* [Provide a correction](#2-provide-a-correction)
* [Refine your question](#3-refine-your-question)

## 1. Rate an answer

After WisdomAI provides an answer, you will see thumbs-up (👍) and thumbs-down (👎) icons.

* **Click Thumbs Up (👍):** Use this if the answer is accurate, relevant, and helpful. This positive reinforcement helps the system understand what a good response looks like.
* **Click Thumbs Down (👎):** Use this if the answer is incorrect, incomplete, or unhelpful. This flags the response for review.

## 2. Provide a correction

When you click **Thumbs Down (👎)**, you will be prompted to provide more details. This is the most direct way to teach the system.

* **If the answer is incorrect:** Provide the correct answer in the text field.
* **If the answer is incomplete:** Add the missing context or information.

<img alt="Image showing the Thumb Down action in chat" title="Thumb Downv2 Pn" />

<img alt="Image showing the Thumb Down action in chat" title="Thumb Downv2 Pn" />

## 3. Refine your question

You can also provide feedback by rephrasing your original question. If an initial query does not provide the desired result, refining it with more specific details helps WisdomAI learn to interpret user intent better.

<Note>
  For advanced tasks like editing the SQL query or managing validated queries, you must be an Administrator. See the [Validate and Test Answers](/improve-wisdom-ai-responses/validate-and-test-answers) guide for admin-specific workflows.
</Note>

## Next steps

<CardGroup>
  <Card title="Connect and Test Tutorial" icon="rocket" href="/setting-up-wisdom-ai/basic-tutorial-connect-and-test">
    Walk through the initial setup to connect a data source and run your first query.
  </Card>

  <Card title="Validate and Test Answers" icon="book-open" href="/improve-wisdom-ai-responses/validate-and-test-answers">
    Test and validate both natural language responses and SQL query results directly within the chat interface.
  </Card>
</CardGroup>


# Reviewed Queries
Source: https://docs.wisdom.ai/setting-up-wisdom-ai/feedback-mechanisms/reviewed-queries



Reviewed queries are curated pairs of a natural language question and its ideal SQL response. They serve as a powerful tool to guarantee accuracy, especially for business-critical calculations or complex metrics that require a specific SQL structure, such as window functions or nested queries.

By building a repository of these pre-vetted queries, you ensure that everyone in your organization receives consistent, accurate answers to the most important questions. This is the most critical aspect of context for the language model to understand your data, as it provides direct, unambiguous examples of how to query your tables.

## Create Reviewed Queries

There are two primary ways to add queries to your knowledge base: directly from the chat interface or in bulk using a CSV file.

### Create from the chat interface

The most common workflow is to validate queries as you interact with the system. This allows you to refine the AI's generated SQL or provide your own from scratch.

An easy workflow to define reviewed queries is to ask the question in the chat, provide feedback or edit the generated SQL, and then validate the response.

1. Ask a question and review the generated answer.
2. If the answer is correct, click the **thumbs-up** icon.
   <Note>
     Currently, feedback icons (thumbs-up and thumbs-down) appear only for responses containing charts or structured data. Feedback for text-only responses is not yet supported but will be available in a future update.
   </Note>
3. In the **Review a Question** modal that appears, confirm or edit the natural language question that the SQL code answers.
4. After confirmation, the query will be saved and listed in the **Context > Reviewed Queries** tab.

The following code block shows an example query to calculate the win rate for sales, validated by clicking the thumbs-up button.

```text theme={null}
SELECT 
  SAFE_DIVIDE(
    SUM(CASE WHEN `stage_label` = 'Closed Won' THEN `acv` ELSE 0 END), 
    SUM(`acv`)
  ) AS `win_rate`
FROM `wisdom-staging-406623`.`b2bsaleshomebrew`.`Opportunity`
WHERE `stage_label` IN ('Evaluation', 'Negotiation', 'Closed Loss', 'Closed Won');
```

<Frame>
  <img alt="Image showing the Review a Question modal" />

  <img alt="Image showing the Review a Question modal" />
</Frame>

5. If the answer needs changes, click the **Edit** button (pencil icon) to modify the SQL. Once you are satisfied, click **Mark as reviewed**.

### Example: Editing a query for granularity

This example shows how to refine a query to get a more detailed view of your data.

Suppose you ask, **“Show me the yearly ARR trend,”** and the system generates the following correct, but high-level, query:

```text theme={null}
SELECT
  DATE_TRUNC(`close_date`, YEAR) AS `year`,
  SUM(`acv`) AS `arr`
FROM
  `wisdom-staging-406623`.`b2bsaleshomebrew`.`Opportunity`
WHERE
  `stage_label` = 'Closed Won'
GROUP BY
  `year`
ORDER BY
  `year` ASC
```

The chart shows a clear year-over-year trend. However, you decide that a **quarterly view** would be more insightful for tracking seasonal performance. To do this, click the **Edit** button (the pencil icon) to modify the SQL directly.

<Frame>
  <img alt="Image showing the Edit Sql option in chat" />

  <img alt="Image showing the Edit Sql option in chat" />
</Frame>

The only change needed is to adjust the `DATE_TRUNC` function from `YEAR` to `QUARTER`.

Here is the **edited SQL**:

```text theme={null}
SELECT
  DATE_TRUNC(`close_date`, QUARTER) AS `quarter`,
  SUM(`acv`) AS `arr`
FROM
  `wisdom-staging-406623`.`b2bsaleshomebrew`.`Opportunity`
WHERE
  `stage_label` = 'Closed Won'
GROUP BY
  `quarter`
ORDER BY
  `quarter` ASC
```

<Frame>
  <img alt="Image showing the Edited SQL" />

  <img alt="Image showing the Edited SQL" />
</Frame>

After applying the change and seeing the updated quarterly chart, you can save this improved version. You would click **Mark as reviewed** and update the question to **“Show me the quarterly ARR trend”** to save it as a new, more specific Validated Query for future use.

<Frame>
  <img alt="Image showing the Review a Question modal" />

  <img alt="Image showing the Review a Question modal" />
</Frame>

### Bulk upload with CSV

For adding many validated queries at once, you can use the import CSV option in the **Context** > **Reviewed Queries** tab. This is ideal for migrating existing reports or defining a set of canonical metrics from the start.

Create a CSV file with the required column headers. By default, the CSV must include `Query` and `SQL`. Populate each row with a natural language question and its corresponding SQL statement.

<Note>
  If your domain contains multiple database connections, the CSV file must include the following three exact column headers: `Query`, `SQL`, and `Connection`. The `Connection` column should contain the name of the database connection exactly as it appears on the Connections page in WisdomAI (for example, `SNOWFLAKE-dev`). If the `Connection` column is missing, its header is renamed, or the specified connection name does not match an existing connection, the CSV upload will fail.
</Note>

<Frame>
  <img alt="Import CSV File button shown" />

  <img alt="Import CSV File button shown" />
</Frame>

## Best practices for well-formed SQL

For a reviewed query to be effective and reusable, follow these best practices when writing your SQL:

* **Keep it concise and readable:** Write SQL that is easy to understand. If the logic is complex, use comments or break it down.
* **Split complex examples:** Instead of creating one example that calculates multiple metrics (e.g., “Show revenue and ARR trend”), split it into two separate, focused examples (“Show revenue trend” and “Show ARR trend”).
* **Use CTEs for complex logic:** If the SQL requires multiple steps or transformations, break it down into more understandable Common Table Expressions (CTEs).
* **Be consistent:** Use a consistent SQL structure for different variations of the same metric. For example, the queries for “Yearly trend of ARR” and “ARR by segment” should be built from a consistent base calculation of ARR, ideally using the same CTE.

## Combining with language Knowledge for complex cases

While reviewed queries are powerful, some complex business rules are best enforced by pairing them with explicit instructions in your **language knowledge**. Reviewed queries teach the model *how* to calculate a specific metric, while language knowledge can teach it *what not to do* to avoid common logical errors.

For instance, imagine you have a `statewise_population` table with a pre-aggregated `country_population` column. Summing this column across multiple states from the same country would lead to massive double-counting.

While a validated query can show the correct way to get the population, adding a clear instruction in [language knowledge](/setting-up-wisdom-ai/advanced-data-modeling-creating-context#natural-language-knowledge) provides an extra layer of protection against mistakes:

**Instruction Example:** “Never sum up the `country_population` column across different rows for the same country.”

Using both features together ensures that even when the AI generates new or slightly different queries, it still adheres to your most important business logic.

## Manage Reviewed Queries

As a Domain Data Admin, you can edit a reviewed query or reopen the conversation where it was created.

* To edit a reviewed query, click the query row and update the query text as needed.
* To reopen the original query workflow, click the **Open conversation** icon. This opens the conversation where the query was validated, allowing you to re-ask the question, modify the visualization, refine the query, edit its SQL, or regenerate the results.

<Frame>
  <img alt="Edit Reviewed Queries Chat" />

  <img alt="Edit Reviewed Queries Chat" />
</Frame>

## Next steps

<CardGroup>
  <Card title="Limited Knowledge" icon="puzzle-piece" href="/setting-up-wisdom-ai/feedback-mechanisms/limited-context">
    Understand how to identify and flag when the system's answers lack necessary context.
  </Card>

  <Card title="Provide Feedback to the System" icon="thumbs-up" href="/setting-up-wisdom-ai/feedback-mechanisms/provide-feedback-to-the-system">
    Learn how to rate answers and provide corrections to improve the system's accuracy.
  </Card>

  <Card title="Monitor Negative Feedback" icon="thumbs-down" href="/setting-up-wisdom-ai/feedback-mechanisms/monitor-negative-feedback">
    Track and analyze negative user feedback to identify areas for system improvement.
  </Card>

  <Card title="Turn Answers into Dashboards" icon="book-open" href="/using-wisdom-ai-everyday/turn-answers-into-dashboards">
    Compile key insights and visualizations into a shareable, narrative-driven report.
  </Card>
</CardGroup>


# Advanced Tab
Source: https://docs.wisdom.ai/setting-up-wisdom-ai/manage-domains/advanced-tab



The Advanced tab provides granular control over various operational and presentation aspects of your domain. You can fine-tune display preferences, set fiscal year configurations, and customize the AI's behavior.

This section allows you to configure these settings:

* **Starter Questions:** A list of predefined questions to guide new users.
* **Fiscal Year Configuration:** Settings to define your fiscal year start month and end calendar year.
* **Jobs**: Manage job schedules and view run logs for domain jobs.
* **Column Crawl Schedule:** Configure when the domain crawl should run. You can also disable crawl from here.
* **Display Preferences:** Toggles for compact number display and automatic data panel opening.
* **Row Level Security Config:** Enable or disable this configuration for Admin users.
* **Chat Customization:** A text area for providing system instructions to the AI, for example, "*Always reply in English*".

<Frame>
  <img alt="UI snippet showing the Advanced Tab" />
</Frame>


# Changelog Tab
Source: https://docs.wisdom.ai/setting-up-wisdom-ai/manage-domains/changelog-tab



The Changelog tab provides a chronological record of updates applied to the domain, helping you understand what changed, when it changed, and who made the change.

It captures modifications across domains, such as updates to Context items, configuration settings, or other domain-level objects. Each entry includes the time of the change, the domain version, the user who performed the action, the change type (for example, added), and a brief summary of the update.

Use this tab to track recent activity, audit configuration changes, and troubleshoot unexpected behavior by correlating changes with their impact on the domain.

<Frame>
  <img alt="Snippet showing the Changelog Tab within a domain" />

  <img alt="Snippet showing the Changelog Tab within a domain" />
</Frame>


# Context Tab
Source: https://docs.wisdom.ai/setting-up-wisdom-ai/manage-domains/context-tab



The Context tab is where you define how the AI should understand and respond to your business. Here, you provide domain-specific knowledge, terminology, metrics, and validated examples that help ensure responses are accurate, consistent, and aligned with your definitions.

Rather than changing the underlying model, this section provides guidance that shapes how the AI interprets questions and generates answers based on your data and business rules.

The Context tab includes six sub-tabs:

* [Knowledge](#knowledge)
* [Reviewed Queries](#reviewed-queries)
* [Metrics](#metrics)
* [Synonyms](#synonyms)
* [Entities](#entities)
* [Skills](#skills)

### **Knowledge**

Use this sub-tab to define background information that helps the AI understand the expected answer type, audience, and format. You can:

* Add knowledge entries manually
* Upload or download knowledge entries in bulk
* Search for specific knowledge entries
* Edit or delete existing knowledge
  <Note>
    To learn more about how Knowledge works, read the related article [Advanced Data Modeling: Creating Context](/setting-up-wisdom-ai/advanced-data-modeling-creating-context).
  </Note>

<Frame>
  <img alt="Snippet showing the Context Tab" />

  <img alt="Snippet showing the Context Tab" />
</Frame>

### **Reviewed Queries**

Use this sub-tab to manage reviewed question-and-answer pairs that define how the AI should respond to specific user queries.

Reviewed queries are natural language questions that have been manually reviewed and refined by a subject matter expert to ensure that:

* The question is clear and well-structured
* The intended meaning is correct
* The AI produces a consistent and trustworthy answer when the query is reused

You can upload and download reviewed queries as CSV files, search for specific queries, and see who reviewed each one.

<Note>
  To learn more about Reviewed Queries, read the related article [Validate and Test Answers](/improve-wisdom-ai-responses/validate-and-test-answers)
</Note>

<Frame>
  <img alt="Snippet showing the Reviewed Queries tab" />

  <img alt="Snippet showing the Reviewed Queries tab" />
</Frame>

### **Metrics**

Use this sub-tab to define custom business metrics that the AI can reference and explain consistently.

You can create metrics and manage their visibility, names, descriptions, and display formats. Defining metrics ensures the AI uses the same definitions and calculations your business relies on.

<Note>
  To learn more about how Metrics work, read the related article [How to Create Metrics](/improve-wisdom-ai-responses/how-to-create-metrics).
</Note>

<Frame>
  <img alt="Snippet showing the Metrics Tab" />

  <img alt="Snippet showing the Metrics Tab" />
</Frame>

### **Synonyms**

Use this sub-tab to define groups of words or phrases that should be treated as the same business concept.

Synonym sets help the AI recognize different ways users may refer to the same idea, improving query understanding and retrieval accuracy. This is especially useful for:

* Abbreviations and acronyms
* Aliases and alternative names
* Industry-specific or regional terminology

For example, you can define a synonym set for *the USA* that includes the *United States*, *the United States of America*, and the *U.S.*, ensuring all variations are interpreted consistently.

You can create synonym sets manually by clicking on **+ Add Synonym Set** or import and export them in bulk using CSV files.

<Frame>
  <img alt="Image showing the Synonyms tab" />

  <img alt="Image showing the Synonyms tab" />
</Frame>

### **Entities**

Use this sub-tab to define the key business entities that are central to your domain, such as *Accounts*, *Customers*, or *Opportunities*.

Entities represent meaningful business concepts that the AI should recognize and refer to in natural language, rather than technical identifiers or internal IDs. Defining entities helps align AI responses with how your business actually talks about its data, resulting in a clearer, more intuitive chat experience.

You can define entities by specifying name columns, ID columns, default sorting, and related columns.

<Frame>
  <img alt="Snippet showing the Entities Tab" />

  <img alt="Snippet showing the Entities Tab" />
</Frame>

### **Skills**

Use this sub-tab to create and manage reusable task-specific guidance that WisdomAI follows when it recognizes a matching request.

Skills standardize recurring analysis workflows so WisdomAI follows the same process consistently across all users. Each skill has a name, a description that tells WisdomAI when to activate it, and a body of instructions.

<Note>
  To learn how Skills work and how to create them, read [Understand Skills](/setting-up-wisdom-ai/manage-domains/skills) and [Create a Skill](/setting-up-wisdom-ai/manage-domains/create-a-skill).
</Note>


# Create a Skill
Source: https://docs.wisdom.ai/setting-up-wisdom-ai/manage-domains/create-a-skill



There are two ways to create a skill: directly through the Skills tab in domain settings, or by using the `skill-creator` system skill in chat to generate a complete draft.

## Before you begin

* You need domain write access (Administrator or Data Administrator) to create, edit, or delete skills. See [Access Management](/manage-account/access-management) for a full breakdown of roles and permissions.
* Explorers can trigger skill activation in chat, including explicit `/skill-name` invocation, but can't create, edit, or delete skills. They can also run `skill-creator` and get a full draft back in chat, but since Explorers do not have create or write access, the draft is not saved to the domain.
* Skills work best on top of well-configured domains. If a data source is poorly described or tables are not crawled, a skill cannot compensate for that. Set up your data model first. See [Advanced Data Modeling](/setting-up-wisdom-ai/advanced-data-modeling-creating-context).

## Create a skill from a domain

1. Navigate to the domain, then select the **Context** tab.
2. Select the **Skills** sub-tab.
3. Click **Add Skill**.
4. Fill in the three fields in the **New Skill** modal:
   * **Name**: a lowercase, hyphenated identifier (e.g. `revenue-analysis`). This is also the identifier for explicit `/skill-name` invocation in chat.
   * **Description**: describe when WisdomAI should activate this skill. The field includes a "Guide to optimizing skill descriptions" helper link.
   * **Instructions**: the full guidance: steps, data source rules, output expectations, and business logic.
5. Click **Save**.

<img alt="Modal showing the skills creation steps" />

## Tips for writing effective skills

* Create skills for the top recurring question and analysis types in your domain.
* If a Knowledge entry is longer than approximately 500 words and contains step-by-step workflows or query templates, consider converting it to a skill instead.
* Match the phrasing your users would naturally type for the description. Vague descriptions cause the skill to activate too broadly or not at all.
* If your instructions include conditional phrasing like "when a user asks," "if the user asks," or "use this for X analysis," that's a sign the content belongs in a skill.

## Create a skill using `skill-creator` in chat

`skill-creator` is a built-in system skill that generates a complete skill draft (name, description, and instructions) from a natural-language workflow description.

1. Open a chat in the domain.
2. Describe your workflow in natural language. For example: "Can you create a skill for analyzing client performance improvement?"
3. WisdomAI loads `skill-creator` and generates a complete draft.
4. Review the draft. If you are an Administrator or Data Administrator, WisdomAI saves the skill directly to your domain.

<Note>
  Ask WisdomAI to revise an existing skill, evaluate its quality, or generate test prompts to verify activation, all by continuing the conversation with `skill-creator`.
</Note>

<video />

## Verify the skill works

1. Open a chat in the domain and send a message you expect to trigger the skill.
2. Check for the "Skill loaded: `skill-name`" indicator in the conversation. Expand it to confirm the correct skill was activated.

To invoke the skill directly, type `/skill-name` in the chat input.

## Edit or delete a skill

* **Edit**: open the Skills tab, click the three-dot menu on the skill row, and select **Edit**. Every edit creates a new version. The domain links to the version saved at that point, so updates are explicit and do not silently change behavior.
* **Delete**: click the three-dot menu and select **Delete**. Deleting a skill is permanent.

<Note>
  System skills (Created By: Wisdom Internal) are read-only and cannot be edited or deleted.
</Note>

<CardGroup>
  <Card title="Skills Overview" icon="book-open" href="/setting-up-wisdom-ai/manage-domains/skills">
    Understand how Skills work and how they differ from Knowledge.
  </Card>

  <Card title="Context Tab" icon="layer-group" href="/setting-up-wisdom-ai/manage-domains/context-tab">
    Explore all context-building tools available in your domain settings.
  </Card>

  <Card title="Advanced Data Modeling" icon="sitemap" href="/setting-up-wisdom-ai/advanced-data-modeling-creating-context">
    Build a well-configured domain before adding skills for best results.
  </Card>
</CardGroup>


# Data Sources Tab
Source: https://docs.wisdom.ai/setting-up-wisdom-ai/manage-domains/data-sources-tab



The Data Sources section is where you manage and model the raw data that WisdomAI accesses and interprets. This configuration is fundamental to making your data queryable, connected, and meaningful.

Within this section, you define which data sources are available to the AI, how structured data is modeled, and how file-based content is indexed. Properly configuring data sources ensures WisdomAI understands both the structure and context of your information.

<Frame>
  <img alt="Snippet showing the Data Sources tab within a domain" />

  <img alt="Snippet showing the Data Sources tab within a domain" />
</Frame>

The Data Sources section includes the following tabs:

* **Database**: Use this tab to manage tables sourced from a connected database (for example, BigQuery). You can control which database tables are visible to the AI, add display names and descriptions, and [define relationships between tables](/setting-up-wisdom-ai/advanced-data-modeling-creating-context#establishing-relationships) to accurately model your data. This view also lets you review key schema details, such as columns, derived fields, and RAG-enabled data.
* **Tabular Uploads**: Use this tab to upload structured files, such as CSV or Excel, and create tables manually within the domain. These uploaded tables behave like database tables for querying, allowing you to control visibility, add descriptions, and review the columns and data types from the uploaded file.
* **Files**: Use this tab to upload and manage unstructured files that provide additional context to the AI responses.
* **MCP Servers**: If an MCP server is connected, this tab displays the server's tools and configuration. See [Connect an MCP Server](/getting-started/connect-data-sources/connect-mcp-server) for details.
* **Web Search**: If Web Search is enabled, this tab lets you configure the source policy that controls which websites the AI can search. See [Search the Web](/getting-started/connect-data-sources/search-the-web) for details.
  <Note>
    This feature is in beta. Currently, PDFs, DOC/DOCX files, PowerPoint files, txt files, and images are supported.
  </Note>


# Evaluation Tab
Source: https://docs.wisdom.ai/setting-up-wisdom-ai/manage-domains/evaluation-tab



The Evaluation tab is used to test and validate AI behavior within a domain. Within this section, you can create specific sets of prompts to simulate user interactions. Provide expected SQL outputs alongside these prompts to directly measure the AI's accuracy in translating natural language into correct database queries. After running evaluations, you can review the results to identify areas for improvement.

<Frame>
  <img alt="UI snippet showing the Evaluation Tab" />

  <img alt="UI snippet showing the Evaluation Tab" />
</Frame>

### **Evaluation Sets**

Create and manage collections of prompts for evaluating AI behavior. Add a new evaluation set by providing a name and a JSON definition containing prompts, optionally including expected SQL. Existing evaluation sets are listed in this view, allowing you to review and manage them over time.

### **Evaluation Runs**

Find a list of completed evaluation runs and their results. This view allows you to review past executions, compare outcomes, and track how AI performance changes over time.

<Note>
  To learn how to create an Evaluation Set, understand indicators, and review results, consult the related article [Use Evaluation Sets and Runs](/improve-wisdom-ai-responses/use-evaluations-sets-and-runs).
</Note>


# Overview Tab
Source: https://docs.wisdom.ai/setting-up-wisdom-ai/manage-domains/overview-tab



The Overview tab serves as a central dashboard, providing a high-level summary of your domain's health, content, and activity. You can quickly grasp key metrics and statuses at a glance.

<Frame>
  <img alt="Snippet showing the Overview tab for the B2B Sales Domain" />

  <img alt="Snippet showing the Overview tab for the B2B Sales Domain" />
</Frame>

The Overview tab displays the following options:

* **Domain name and description:** Displays the domain title and a short description.
* **Queries:** Shows the total number of queries and a 30-day usage trend.
* **Context:** Provides a count of configured Knowledge entries, Metrics, and Reviewed Queries.
* **Connected data sources:** Displays one card per connected data source (for example, database connections or file uploads), including:
  * Number of tables
  * Number of columns
  * Last synchronization status
* **MCP Servers:** If connected, displays one card per MCP server showing the server name, total number of tools, and how many tools are enabled.
* **Web Search:** If enabled, displays a card showing the current source policy (Allowlist, Blocklist, or All domains) and the number of configured domains.
* **Files:** Indicates the number of datasets and uploaded files associated with the domain.
* **Starter Questions:** Lists example questions configured to guide new users.

<Frame>
  <img alt="Show the relationship diagram" />

  <img alt="Show the relationship diagram" />
</Frame>

From the Overview tab, you can also switch to a diagram view that visualizes the domain’s data model. This view displays:

* Tables as nodes
* Relationships between tables
* Key columns used to join data

Use the diagram view to quickly understand how entities relate to one another and to validate the domain's overall structure at a glance.

<Note>
  The diagram view is read-only and is intended for exploration and orientation. To manage tables or relationships, use the [Data Sources](/setting-up-wisdom-ai/manage-domains/data-sources-tab) tab.
</Note>


# Understand Skills
Source: https://docs.wisdom.ai/setting-up-wisdom-ai/manage-domains/skills



Skills are reusable blocks of instructions created by domain and data admins that tell WisdomAI how to handle specific types of messages. When you send a message, WisdomAI checks which skills are available for your domain and loads the most relevant one, ensuring the same instructions are followed consistently every time.

<Note>
  * Skills is currently in beta and available to all accounts. Administrators and Data Administrators can create, edit, and delete skills.
  * Explorers can trigger skill activation in chat, including explicit `/skill-name` invocation, but can't create, edit, or delete skills. Explorers can also run `skill-creator` and get a full draft back in chat, but since Explorers do not have create or write access, the draft is not saved to the domain.
</Note>

## What a skill contains

Each skill has three components:

* **Name**: a stable, lowercase, hyphenated identifier (e.g. `revenue-analysis`). Also used for explicit `/skill-name` invocation in chat.
* **Description**: the trigger signal. Tells WisdomAI when to activate the skill.
* **Instructions**: the full guidance: steps, data source rules, output expectations, and business logic.

Each skill is a Markdown document with YAML frontmatter:

```
---
name: skill-name
description: What this skill does and when to activate it.
---

Instructions go here.
```

## How WisdomAI activates a skill

When you send a message in a domain with skills configured:

1. WisdomAI resolves which skills are available for your domain.
2. The agent sees a compact list of available skills — name and description only.
3. The agent selects the most relevant skill for the request.
4. The full skill instructions are loaded into the agent's context.
5. The agent responds using the skill guidance.

If no skill matches, WisdomAI answers normally without loading any skill.

### Explicit invocation

Type `/skill-name` in the chat input to invoke a skill directly, bypassing automatic selection. This is useful for testing a skill or for power users who know exactly which workflow to run.

<Note>
  Explorers do not have access to the Skills tab and can't browse the list of configured skills. If your team relies on explicit invocation, share skill names with Explorers directly so they know what to type.
</Note>

### Skill loaded indicator

When a skill activates, WisdomAI displays a "Skill loaded: `skill-name`" indicator in the conversation. Expand it to see which skill was used and inspect its details.

## Skills vs. Knowledge

|                 | Knowledge                                                                         | Skills                                                                                               |
| --------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| What it stores  | Facts, definitions, reference information                                         | Task-specific guidance and workflows                                                                 |
| Think of it as  | A company wiki entry                                                              | A standard operating procedure                                                                       |
| Example content | "Account managers refer to the business consultants who manage that client group" | "When asked to analyze ARR: use net revenue, exclude test accounts, follow this 4-step workflow\..." |
| When it loads   | Retrieved at the start of the turn based on your message                          | WisdomAI sees name and description first, then loads full instructions when the request matches      |
| Versioned       | No                                                                                | Yes — edits create a new version                                                                     |

If it is a fact WisdomAI should know, it belongs in Knowledge. If it is a workflow or set of instructions WisdomAI should follow for a specific task, it belongs in Skills.

Avoid these common mistakes:

* Do not put query templates or step-by-step analysis workflows in Knowledge.
* Do not put metric definitions or data dictionaries in Skills.

## System skills

WisdomAI includes built-in, read-only system skills that are always available and do not need to be added manually. The main system skill is `skill-creator`, which generates a complete skill draft (name, description, and instructions) from a natural-language workflow description you give it in chat.

<Note>
  To learn how to use `skill-creator` to author a skill, read [Create a Skill](/setting-up-wisdom-ai/manage-domains/create-a-skill).
</Note>

## Skills tab reference

Find below references for the Skills tab fields.

### Skills list

The **Skills** tab displays a table with three columns:

| Column      | Description                                                                |
| ----------- | -------------------------------------------------------------------------- |
| Skill       | The skill name (Format must be lowercase, hyphenated)                      |
| Description | The description added for that skill                                       |
| Created By  | The username who created the skill, or "Wisdom Internal" for system skills |

The three-dot menu on each row provides **Edit** and **Delete** options. These actions require domain admin access.

### Skill detail view

Clicking a skill opens a detail modal showing the full description and instructions. The modal has **Close** and **Edit** buttons. If you have read-only access, you can view skill details but cannot modify them.

## Permissions

| Role               | View Skills tab | Create, edit, delete | Trigger activation in chat |
| ------------------ | --------------- | -------------------- | -------------------------- |
| Administrator      | ✅               | ✅                    | ✅                          |
| Data Administrator | ✅               | ✅                    | ✅                          |
| Explorer           | ❌               | ❌                    | ✅                          |
| Observer           | ❌               | ❌                    | ❌                          |

Creating, editing, and deleting skills requires domain write access (Administrator or Data Administrator). Explorers can't see the Skills tab or the list of configured skills, but skills still activate automatically for their messages when relevant, and they can invoke a skill directly with `/skill-name` if they already know its name. Observers cannot use chat at all, so skills do not apply to them. User-level skills scoped to individual users are not yet available.

<Note>
  To create, edit, or delete a skill, read [Create a Skill](/setting-up-wisdom-ai/manage-domains/create-a-skill).
</Note>

## Next steps

<CardGroup>
  <Card title="Create a Skill" icon="wand-magic-sparkles" href="/setting-up-wisdom-ai/manage-domains/create-a-skill">
    Use skill-creator to draft and save a new skill from a plain-language description.
  </Card>

  <Card title="Context Tab" icon="layer-group" href="/setting-up-wisdom-ai/manage-domains/context-tab">
    See how Skills relate to the other context types WisdomAI can load.
  </Card>
</CardGroup>


# SQL Playground Tab
Source: https://docs.wisdom.ai/setting-up-wisdom-ai/manage-domains/sql-playground-tab



The SQL Playground tab provides an interactive environment for writing and executing SQL queries on the domain’s connected data sources. It allows you to inspect tables, validate joins, and test aggregations by writing and running SQL queries against the domain’s connected data sources, with results returned immediately.

Use this tab to explore the underlying data model, troubleshoot query logic, and validate SQL outputs independently of the AI-generated responses.

The SQL Playground is intended for manual exploration and validation. For testing AI behavior using predefined prompt sets and expected SQL outputs, use the Evaluation tab.

<Frame>
  <img alt="Sql Playground Tab" />

  <img alt="Sql Playground Tab" />
</Frame>


# Understand Domains
Source: https://docs.wisdom.ai/setting-up-wisdom-ai/manage-domains/understand-domains



Domains define how WisdomAI accesses data, understands business context, and evaluates the accuracy of its responses. All configuration related to data modeling, AI behavior, and quality control is managed at the domain level.

<Frame>
  <img alt="Snippet showing the Overview tab of a Domain" />

  <img alt="Snippet showing the Overview tab of a Domain" />
</Frame>

WisdomAI organizes domain configuration into distinct areas, each representing a key aspect of how the system understands and interacts with your data.

Explore the individual tab pages linked below for detailed configuration guidance, best practices, and examples.

* [**Overview**](/setting-up-wisdom-ai/manage-domains/overview-tab): Monitor domain health, usage, and structure at a glance.
* [**Data Sources**](/setting-up-wisdom-ai/manage-domains/data-sources-tab): Define which tables and files the AI can access and how they relate.
* [**Context**](/setting-up-wisdom-ai/manage-domains/context-tab): Provide business context, metrics, entities, and validated queries that shape AI understanding.
* [**Changelog**](/setting-up-wisdom-ai/manage-domains/changelog-tab): Track configuration changes made to the domain over time.
* [**Advanced**](/setting-up-wisdom-ai/manage-domains/advanced-tab): Configure display preferences, fiscal settings, and AI behavior.
* [**Evaluation**](/setting-up-wisdom-ai/manage-domains/evaluation-tab): Test and validate the AI’s performance using structured prompt sets and expected SQL outputs.
* [**SQL Playground**](/setting-up-wisdom-ai/manage-domains/sql-playground-tab): Explore and test SQL queries against the domain’s data.


# Advanced Column Options
Source: https://docs.wisdom.ai/setting-up-wisdom-ai/manage-tables-columns/advanced-column-options



If you toggle the **Show advanced options** switch on, the following additional configuration fields will appear, allowing for more granular control over your data model:

| **Field**                | **Description**                                                                                                                                                    |
| :----------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Primary Key**          | Identifies if the column is a unique identifier for the rows in the table.                                                                                         |
| **Default Order**        | Sets the default sorting direction (Ascending or Descending) for the column.                                                                                       |
| **Allowed values**       | Defines a list of valid entries to guide WisdomAI's understanding of the column's content. These values are case-sensitive and are used for semantic context only. |
| **Order allowed values** | Enables or disables a specific custom sorting order for the defined allowed values. This custom sequence overrides the Default Order setting.                      |
| **User identifier**      | Marks the column as containing user-specific identifying information such as email or username.                                                                    |
| **Enable Lookups**       | Toggles whether this column can be used for data lookup operations and Name-Entity Recognition (NER).                                                              |

## Understanding lookups and NER

Enabling lookups on textual columns powers Name-Entity Recognition (NER). This helps Wisdom build more accurate SQL queries by mapping user intent to specific database values. The key benefits of enabling this feature are:

* **Token matching**: WisdomAI identifies the right column to query based on tokens in the question string. For example, "Show me total usage for compute services" will match `service_category = compute`, whereas "total usage for EC2 services" will match `service_name = compute`.
* **Typo correction**: Fixes minor typos in user questions. For example, "Show me total usage for computer services" will be auto-corrected to `service_category = compute`.

<Tip>
  Enable lookups on **VARCHAR** type columns that contain categorical dimensions, such as region names, customer names, or category types.
</Tip>

<img alt="A table view of database columns showing advanced configuration options, such as Primary Key and Allowed Values, enabled by the &#x22;Show advanced options&#x22; toggle." />

<img alt="A table view of database columns showing advanced configuration options, such as Primary Key and Allowed Values, enabled by the &#x22;Show advanced options&#x22; toggle." />

## Next Steps

<CardGroup>
  <Card title="Advanced Data Modeling" icon="sitemap" href="/setting-up-wisdom-ai/advanced-data-modeling-creating-context">
    Define relationships and context in your data to enable more powerful analysis.
  </Card>

  <Card title="Provide Feedback to the System" icon="thumbs-up" href="/setting-up-wisdom-ai/feedback-mechanisms/provide-feedback-to-the-system">
    Learn how to rate answers and provide corrections to improve the system's accuracy.
  </Card>

  <Card title="Understand Domains" icon="sliders" href="/setting-up-wisdom-ai/manage-domains/understand-domains">
    Manage and customize your data domains to refine context and improve query results.
  </Card>
</CardGroup>


# Document Tables and Columns
Source: https://docs.wisdom.ai/setting-up-wisdom-ai/manage-tables-columns/document-tables-and-columns



Proper documentation of tables and columns provides the foundational context required for formal semantic modeling. This initial step is essential for translating technical database structures into familiar business concepts and is critical for data governance, user understanding, and effective analytics. This guide will show you how to do it.

## Document tables

For each table in your data model, you can configure the following fields:

| **Field**        | **Description**                                                                                                                                                                                                                                       | **Example**                                                                                                                                                                                                                                                                                                                                             |
| :--------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Display Name** | A business-friendly alias that replaces technical or system-generated table names. You can assign unique display names to the same table across different domains. If left blank, the system defaults to the technical table name for SQL generation. | The table named "contact" can be displayed as "B2B Contact Details" to clarify the type of contact data it represents.                                                                                                                                                                                                                                  |
| **Description**  | In this field, you should provide a clear explanation of what the table represents, focusing on a concise, plain-English description of each row’s purpose and content.                                                                               | This table stores detailed records of business accounts that have monthly revenue exceeding \$10,000. Each row represents a single account and includes fields such as account ID, account name, industry classification, account creation date, current status (active, inactive, suspended), monthly revenue amount, and primary contact information. |

<Tip>
  Always specify the granularity of each row in your table description. This helps analysts understand the level of detail in the data and prevents misinterpretation during analysis.
</Tip>

To Document tables, go to **Domains** > **Select a Domain** > **Data Sources** > **Tables**.

<Frame>
  <img alt="The table is listed with the Display name and Description highlighted" />

  <img alt="The table is listed with the Display name and Description highlighted" />
</Frame>

## Document columns

To document columns, click on the table's name. A new page will open, displaying a list of all the columns in the table. You can configure the following fields:

| **Field**          | **Description**                                                                                                                                                                                                                                                  |
| :----------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Display Name**   | User-friendly name shown in the interface replaces technical or system-generated table names. You can assign unique display names to the same table across different domains. If left blank, the system defaults to the technical table name for SQL generation. |
| **Description**    | Clear explanation of what the column represents in business terms.                                                                                                                                                                                               |
| **Display Format** | A dropdown menu used to specify how data is presented to users. You can choose from options such as **Date, Fiscal Year, Currency, Percentage, or Time** to ensure the AI renders results in the most readable format.                                           |

<Frame>
  <img alt="The column is listed with the Display name and the Descrption highlighted" />

  <img alt="The column is listed with the Display name and the Descrption highlighted" />
</Frame>

## Next steps

<CardGroup>
  <Card title="Advanced Data Modeling" icon="sitemap" href="/setting-up-wisdom-ai/advanced-data-modeling-creating-context">
    Define relationships and context in your data to enable more powerful analysis.
  </Card>

  <Card title="Provide Feedback to the System" icon="thumbs-up" href="/setting-up-wisdom-ai/feedback-mechanisms/provide-feedback-to-the-system">
    Learn how to rate answers and provide corrections to improve the system's accuracy.
  </Card>

  <Card title="Understand Domains" icon="sliders" href="/setting-up-wisdom-ai/manage-domains/understand-domains">
    Manage and customize your data domains to refine context and improve query results.
  </Card>
</CardGroup>


# Set up RAG for Textual Columns
Source: https://docs.wisdom.ai/setting-up-wisdom-ai/manage-tables-columns/set-up-rag



Retrieval-Augmented Generation (RAG) for Textual Columns makes unstructured long texts, such as product reviews or support tickets, available for AI-based summarization and generation.

RAG indexes the content of specific columns so that Wisdom can answer qualitative questions about the data rather than just returning quantitative counts.

## Configuration steps

To configure RAG for a table, follow these steps:

1. Navigate to **Domains** > Select your preferred domain > **Data Sources** > **Tables** and locate the table for which you want to configure RAG columns.
2. Click the **three vertical dots** icon, then click **RAG Settings**.

<img alt="Snippet showing the RAG Settings option selected in a table menu." title="Snippet showing how to open the RAG Settings" />

<img alt="Snippet showing the RAG Settings option selected in a table menu." title="Snippet showing how to open the RAG Settings" />

3. In the **RAG Configuration for Textual Columns** window that opens, complete the following:
   * In the **Text content columns for search** field, select the columns that contain rich text content that will be searched over.
   * In the **Filter columns for queries** field, select columns with structured data (such as IDs or dates) to narrow search results.
   * In the **Primary key** field, choose one or more columns that uniquely identify each row in the table.
   * In the **Description of search columns** text box, write a brief description of what the combination of the search columns represents. This helps the AI better understand the context of your data.
   * (Optional) Click **Advanced Options** to specify **which columns to include for citation titles** **and URLs** in the AI's answers.
4. Click **Save** to apply your settings. A notification will appear confirming that the configuration has been updated and that the data sync has been triggered.

<img alt="RAG Configuration Columns 01 Pn" title="Snippet showing the RAG Configuration Modal" />

<img alt="RAG Configuration Columns 01 Pn" title="Snippet showing the RAG Configuration Modal" />

## Use case example: Analyzing product reviews

Imagine a table containing Amazon product reviews with the following columns: `Review ID`, `Product Name`, `Date`, and `Feedback` (the open-ended field that contains long user-generated texts). To enable thematic analysis, you would configure the table as follows:

| **Configuration Field**     | **Selected Column**    | **Purpose**                                                         |
| :-------------------------- | :--------------------- | :------------------------------------------------------------------ |
| **Text content for search** | `Feedback`             | Contains the long texts that the AI will summarize.                 |
| **Filters for queries**     | `Product Name`, `Date` | Allows Wisdom to narrow the search to specific items or timeframes. |
| **Primary Key**             | `Review ID`            | Uniquely identifies each row to aid in accurate data retrieval.     |

**This setup would enable WisdomAI to answer these kinds of questions:**

* "What are the positive themes for feedback on iPhone?"
* "What are people complaining about for the iPhone?"
* "What themes are emerging from feedback about the iPhone?"

<Warning>
  **Filter Limitations**

  If you do not include a column, such as `Date`, in the **Filters for queries** field, WisdomAI cannot effectively use it to narrow down results. For example, if `Date` is not selected as a filter, WisdomAI cannot answer: *"What is the positive feedback for iPhone in 2026?"*
</Warning>

<CardGroup>
  <Card title="Advanced Data Modeling" icon="sitemap" href="/setting-up-wisdom-ai/advanced-data-modeling-creating-context">
    Define relationships and context in your data to enable more powerful analysis.
  </Card>

  <Card title="Provide Feedback to the System" icon="thumbs-up" href="/setting-up-wisdom-ai/feedback-mechanisms/provide-feedback-to-the-system">
    Learn how to rate answers and provide corrections to improve the system's accuracy.
  </Card>

  <Card title="Understand Domains" icon="sliders" href="/setting-up-wisdom-ai/manage-domains/understand-domains">
    Manage and customize your data domains to refine context and improve query results.
  </Card>
</CardGroup>


# API Keys
Source: https://docs.wisdom.ai/settings/api-keys



API keys are bearer tokens that let scripts, integrations, and tools authenticate with the WisdomAI API without going through an interactive login. You manage your keys from the **API Keys** settings page.

Each key **inherits the permissions of the person who created it** — a key can do exactly what its creator can do, and no more. Treat every key like a password.

## Before you start

Every WisdomAI user can create and manage their own API keys — no special role is required. What a key can access is determined by its creator's permissions.

By default, you see only the keys you created. Administrators can also see keys created by other users (see [View other users' keys](#view-other-users-keys)).

## Open the API Keys page

1. In the left-hand navigation, click the **Settings** icon.
2. On the Settings page, select **API Keys**.

<Frame>
  <img alt="Image" />
</Frame>

The page lists your existing keys in a table. Each row shows the key's name and description, a masked fragment of the key, its status, when it was last used, when it expires, and when it was created.

<Frame>
  <img alt="Image" />
</Frame>

## Create an API key

1. Click **Create API key** in the upper-right of the table.
2. In the **Create API key** dialog, fill in the fields:
   * **Name** (required) — a label that identifies where the key is used, for example `Claude Code key` or `Embedding Dashboard`.
   * **Description** (optional) — a note about what the key is for.
   * **Expiration** — how long the key stays valid. Choose **7 days**, **30 days**, **90 days**, **180 days**, **1 year**, or **Never**. The dialog shows the exact expiry date below the field.
   * **Allow impersonation** (optional) — lets the key act on behalf of other users. This toggle only appears for embedded-application use cases. See [Impersonation keys for embedded applications](#impersonation-keys-for-embedded-applications).
3. Click **Create**.

<Frame>
  <img alt="Image" />
</Frame>

<Tip>
  The default expiration is **30 days**. Short-lived keys that you rotate regularly are safer than long-lived ones — only choose **Never** when an integration genuinely cannot support rotation.
</Tip>

### Copy your key

After you click **Create**, WisdomAI shows the new token once, on the **API key created** screen.

1. Click the **copy** icon next to the token, or select the text and copy it manually.
2. Store the token somewhere secure, such as a secrets manager or your integration's environment configuration.
3. Click **Done**.

<Warning>
  The full token is shown **only once**. WisdomAI does not store it in a form that can be displayed again. If you lose the token, [revoke the key](#revoke-an-api-key) and create a new one.
</Warning>

## Use an API key

Pass the token as a bearer token in the `Authorization` header of your API requests:

```text theme={null}
Authorization: Bearer YOUR_API_KEY
```

See the [GraphQL API](/integrations/graphql-api/GraphQL-API) and [MCP Server](/integrations/mcp-server/MCP-Server) documentation for full request examples.

## Impersonation keys for embedded applications

If you embed WisdomAI inside your own application, your backend needs a way to sign each of your end users into WisdomAI. An **impersonation key** makes this possible: it can act on behalf of other users.

Your server uses an impersonation key as the access token for the [`impersonateUser`](/integrations/graphql-api/mutations/auth/impersonate-user) mutation, which returns a short-lived JWT for a specific user. You then pass that JWT into the WisdomAI iframe. See [Impersonate User](/integrations/graphql-api/mutations/auth/impersonate-user) for the full embedded session flow.

### Create an impersonation key

In the **Create API key** dialog, turn on the **Allow impersonation** toggle before you click **Create**.

<Frame>
  <img alt="Image" />
</Frame>

Keys created with this option are marked with an **Impersonator** badge in the table, so you can identify them at a glance.

<Note>
  The **Allow impersonation** toggle appears only when your deployment supports impersonation and your own account is permitted to grant it. If you're building an embedded integration and don't see the toggle, contact [WisdomAI support](/manage-account/contact-support).
</Note>

<Info>
  Impersonation is set when the key is created — it cannot be added to or removed from an existing key. To change it, create a new key and revoke the old one.
</Info>

<Warning>
  An impersonation key can authenticate as any user in your organization, so it is highly privileged. Use it only from your server, never expose it in client-side code, and revoke it immediately if it may have been exposed.
</Warning>

## Understand key status

The **Status** column reflects how close a key is to expiring:

| Status            | Meaning                                                     |
| :---------------- | :---------------------------------------------------------- |
| **Active**        | The key is valid and can be used.                           |
| **Expiring soon** | The key expires within 7 days. Plan to rotate it.           |
| **Expired**       | The key has passed its expiration date and no longer works. |

Expired keys remain in the table for reference but cannot be used or edited. Revoked keys are removed from the table.

## Find a key

When you have many keys, use the controls above the table to narrow the list:

* **Search** — filter by name, description, or the masked key fragment.
* **Status** — show **All statuses**, or only **Active**, **Expiring soon**, or **Expired** keys.

## Edit an API key

You can update a key's **name** and **description** at any time. The token itself, its expiration, and its creator never change.

1. Click the **⋮** (more) menu at the end of the key's row.
2. Select **Edit API Key**.
3. Update the **Name** or **Description**.
4. Click **Save changes**.

<Note>
  Editing is disabled for expired keys. To replace an expired key, create a new one and revoke the old one.
</Note>

## Revoke an API key

Revoking a key permanently disables it. Any application or script using that key immediately loses access.

1. Click the **⋮** (more) menu at the end of the key's row.
2. Select **Revoke API Key**.
3. In the **Revoke access?** dialog, type the key's name to confirm.
4. Click **Revoke**.

<Warning>
  Revoking a key cannot be undone. Make sure no critical integration depends on the key before you revoke it.
</Warning>

<Frame>
  <img alt="Image" />
</Frame>

## View other users' keys

If you are an administrator, a **My keys / All keys** toggle appears next to the status filter:

* **My keys** — shows only the keys you created.
* **All keys** — shows keys created by everyone in the organization. The **Created** column adds the creator's name so you can tell keys apart.

This lets administrators audit and revoke keys across the organization — for example, when a teammate leaves.

## Security best practices

<AccordionGroup>
  <Accordion title="Give each integration its own key">
    Create a separate key per script or integration, with a clear name. If one key is compromised, you can revoke it without disrupting everything else.
  </Accordion>

  <Accordion title="Set an expiration and rotate keys">
    Prefer a fixed expiration over **Never**. Before a key reaches **Expiring soon**, create a replacement, update your integration, and revoke the old key.
  </Accordion>

  <Accordion title="Store tokens securely">
    Keep tokens in a secrets manager or environment variables — never commit them to source control or paste them into shared documents.
  </Accordion>

  <Accordion title="Revoke keys you no longer need">
    Because a key inherits its creator's permissions, an unused key is a standing risk. Revoke keys for retired integrations and for users who have left the organization.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="GraphQL API" icon="code" href="/integrations/graphql-api/GraphQL-API">
    Use your API key to query WisdomAI programmatically.
  </Card>

  <Card title="MCP Server" icon="plug" href="/integrations/mcp-server/MCP-Server">
    Connect WisdomAI to MCP-compatible tools and assistants.
  </Card>

  <Card title="Email Access Control" icon="envelope" href="/settings/email-access-control">
    Control which email domains and addresses can access your instance.
  </Card>

  <Card title="Access Management" icon="key" href="/manage-account/access-management">
    Learn how WisdomAI roles and permissions work.
  </Card>
</CardGroup>


# Connected Apps
Source: https://docs.wisdom.ai/settings/connected-apps

Sign in to OAuth-secured apps so WisdomAI chat agents can act on your behalf.

Connected Apps is where you sign in to the OAuth-secured apps your administrator has set up, so WisdomAI's chat agents can call those tools on your behalf when answering your questions.

Your connections are personal to you. Signing in to or out of an app only affects your own access; other users in the workspace are unaffected.

## Before you start

Every user can manage their own connected apps. No special role is required.

The apps you can sign in to are the OAuth-secured [MCP server](/getting-started/connect-data-sources/connect-mcp-server) connections that an administrator has added on the **Connections** page. If no apps are listed, ask your workspace admin to add one.

## How connected apps work

When an administrator adds an MCP server connection that uses **OAuth** authentication, each user must individually authorize WisdomAI to access it. WisdomAI never stores a single shared credential for these apps.

The Connected Apps page is where you grant that authorization ahead of time. Once you sign in, your chat agents can use the app's tools during chat without interrupting you to authenticate. You can also sign in on demand. If you ask a question that needs an app you haven't connected, WisdomAI prompts you to connect during the chat session.

## Open Connected Apps

1. In the left-hand navigation, click the **Settings** icon.
2. On the Settings page, select **Connected Apps**.

<Frame>
  <img alt="Image" />
</Frame>

The page groups apps into two collapsible sections, each showing a count:

* **Connected**: Apps you have signed in to.
* **Available to connect**: Apps you can sign in to but haven't yet.

<Frame>
  <img alt="Screenshot 2026 05 25 At 4 19 08 PM" />
</Frame>

Each row shows the app's name and the domains it belongs to (for example, *in Sales, Marketing*). Use the **Search apps or domains** box to filter the list.

## Connect an app

1. Find the app under **Available to connect**.
2. Click **Connect**.
3. A secure popup opens. Authorize WisdomAI to access the app.
4. On success, the app moves to the **Connected** section.

<Tip>
  You don't have to connect everything in advance. When a chat question needs an app you haven't signed in to, WisdomAI shows a **Connect** prompt right in the conversation. See [Validate the connection](/getting-started/connect-data-sources/connect-mcp-server#validate-the-connection).
</Tip>

## Reconnect an app

Use **Reconnect** if your access has stopped working or you need to authorize again — for example, to approve updated permissions or if you accidentally authenticated via a different account.

1. In the **Connected** section, open the **⋮** (more) menu on the app's row.
2. Select **Reconnect**.
3. Authorize WisdomAI again in the popup.

<Note>
  Reconnecting first revokes your existing access token for the app, then runs the sign-in flow again.
</Note>

## Disconnect an app

1. In the **Connected** section, open the **⋮** (more) menu on the app's row.
2. Select **Disconnect**.
3. In the **Disconnect from \<app>?** dialog, click **Disconnect**.

<Frame>
  <img alt="Screenshot 2026 05 25 At 4 24 37 PM" />
</Frame>

<Warning>
  Disconnecting revokes your OAuth access token for that app. Any queries or tool calls that depend on the connection will require you to sign in again. This only affects your access — other users in the workspace are unaffected.
</Warning>

## No apps available

If the page shows **Nothing to sign in to yet**, no OAuth-secured apps have been set up for your workspace.

* If you can add connections, add an OAuth-secured MCP server from the [Connections page](/getting-started/connect-data-sources/connect-mcp-server) so your chat agents can act on your behalf.
* Otherwise, ask your workspace admin to add one.

## Next steps

<CardGroup>
  <Card title="Connect to an MCP Server" icon="plug" href="/getting-started/connect-data-sources/connect-mcp-server">
    Add an OAuth-secured MCP server that users can sign in to.
  </Card>

  <Card title="MCP Server" icon="server" href="/integrations/mcp-server/MCP-Server">
    Learn how WisdomAI works with the Model Context Protocol.
  </Card>

  <Card title="API Keys" icon="key" href="/settings/api-keys">
    Create personal bearer tokens for programmatic access.
  </Card>

  <Card title="RBAC for Users" icon="user-shield" href="/integrations/user-management/rbac">
    Control which users and roles can access which apps and permissions.
  </Card>
</CardGroup>


# Email Access Control
Source: https://docs.wisdom.ai/settings/email-access-control



Email Access Control lets administrators define an instance-wide allowlist and blocklist of email addresses and domains. WisdomAI checks these rules whenever a user is invited or attempts to sign in, blocking anyone who doesn't match.

This setting applies to your entire WisdomAI tenant — every organization within it inherits the same rules.

## Before you start

To open this page, you need to be an **Administrator**. See [Access Management](/manage-account/access-management) for details on roles and permissions.

## Open Email Access Control

1. In the left-hand navigation, click the **Settings** icon.
2. On the Settings page, select **Email Access Control**.

<Frame>
  <img alt="Image" />
</Frame>

The page is split into two sections: **Allowlist** and **Blocklist**. Each section has separate controls for **domains** (for example, `company.com`) and individual **email addresses**.

<Frame>
  <img alt="Image" />
</Frame>

## How rules are evaluated

Rules are applied in this order:

1. **Blocklist always wins.** If an email or its domain is on the blocklist, access is denied — even if it also matches an allowlist rule.
2. **If both allowlists are empty, all emails are allowed** (open access). The page shows a warning when this is the case.
3. **If either allowlist has entries**, an email is allowed only if its address or domain matches an allowlist entry.

<Tip>
  Blocked domains can be subdomains of allowed domains. For example, you can allow `company.com` while blocking `contractors.company.com` to grant access to your full-time team but not contractors who use a sub-domain mailbox.
</Tip>

## Manage the allowlist

The allowlist defines who is permitted to access this instance. Leaving both fields empty means anyone can sign in.

<Warning>
  When the allowlist is empty, all email domains will be allowed. You will need to add at least one entry to restrict access.
</Warning>

<Frame>
  <img alt="Image" />
</Frame>

### Allowed Domains

Use this list for domains whose users should all have access (for example, your company domain).

1. In the **Allowed Domains** field, type a domain such as `company.com`.
2. Press **Enter** to add it. The domain appears as a chip below the field.
3. Repeat for each domain you want to allow.
4. To remove a domain, click the **×** on its chip.

### Allowed Email Addresses

Use this list to grant access to specific people whose domains are *not* in the **Allowed Domains** list — for example, an external auditor or partner.

1. In the **Allowed Email Addresses** field, type a complete email such as `partner@external.com`.
2. Press **Enter** to add it.
3. Remove an entry by clicking the **×** on its chip.

## Manage the blocklist

The blocklist denies access to specific domains or addresses, even if they would otherwise be allowed.

### Blocked Domains

Add a domain here to deny access to every user with an email at that domain.

1. In the **Blocked Domains** field, type a domain (for example, `contractors.company.com`).
2. Press **Enter** to add it.
3. Remove an entry by clicking the **×** on its chip.

### Blocked Email Addresses

Add an individual email address here to deny that single user, even if their domain is on the allowlist.

1. In the **Blocked Email Addresses** field, type the full email address.
2. Press **Enter** to add it.
3. Remove an entry by clicking the **×** on its chip.

## Save or discard your changes

After editing the lists, the **Cancel** and **Save** buttons appear at the bottom of the page.

* Click **Save** to apply your changes. New rules take effect immediately for sign-ins and invitations.
* Click **Cancel** to discard unsaved changes and revert to the last saved configuration.

<Note>
  Invalid entries (malformed domains or email addresses) are rejected with an error toast. They are not added to the list and won't be saved.
</Note>

## Examples

<AccordionGroup>
  <Accordion title="Allow only your company's employees">
    Add your corporate domain to **Allowed Domains** (for example, `company.com`). Leave the blocklist empty. Only users with `@company.com` email addresses can sign in.
  </Accordion>

  <Accordion title="Allow your company plus a few external collaborators">
    Add `company.com` to **Allowed Domains** and add each external user's address (for example, `auditor@partner.io`) to **Allowed Email Addresses**.
  </Accordion>

  <Accordion title="Block contractors while allowing the rest of the company">
    Add `company.com` to **Allowed Domains**, then add `contractors.company.com` to **Blocked Domains**. Full-time staff at `@company.com` retain access; contractors at the sub-domain are denied.
  </Accordion>

  <Accordion title="Revoke access for a single user">
    Add the user's full email address to **Blocked Email Addresses**. The blocklist takes precedence over any allowlist match.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="Access Management" icon="key" href="/manage-account/access-management">
    Learn how WisdomAI roles and permissions work.
  </Card>

  <Card title="Manual User Management" icon="users" href="/manage-account/users-management">
    Invite users and assign roles when SSO is not enabled.
  </Card>

  <Card title="Automated Provisioning" icon="user-gear" href="/manage-account/automated-provisioning">
    Provision users automatically through SSO and SCIM.
  </Card>

  <Card title="Manage Organizations" icon="building" href="/access-management/manage-organizations">
    Create isolated organizations within your WisdomAI tenant.
  </Card>
</CardGroup>


# Ask Better Questions
Source: https://docs.wisdom.ai/using-wisdom-ai-everyday/ask-better-questions



Getting useful answers from data starts with asking clear questions. WisdomAI lets you talk to your data simply. This guide explains how to build your questions to get the best possible information and make smart, data-based decisions.

Follow these four key actions to help you obtain precise responses:

<CardGroup>
  <Card title="Make Clear, Natural Language Questions" icon="question" href="#make-clear-natural-language-questions" />

  <Card title="Use Filters for Better Focus" icon="filter" href="#use-filters-for-better-focus" />

  <Card title="Plan for Follow-up Questions" icon="plus" href="#plan-for-follow-up-questions" />

  <Card title="Use Business Terms Set by Admins" icon="check" href="#use-business-terms-set-by-admins" />
</CardGroup>

## Make clear, natural language questions

WisdomAI understands everyday language, but being clear helps it understand you better.

* **Be Specific:** Instead of "Show sales," ask "Show total sales for the last quarter."
* **Use Exact Words:** Say "Count of customers who bought in the last 30 days," not "Customers buying stuff."
* **Ask for Summaries:** If you want totals or averages, say so. For example, "Sum of sales by product" or "Average sales per product."
* **State Time:** Always include dates or periods like "Last month" or "Between January and March 2024."
* **Hint at Connections:** Use words like "by," "who bought," or "per" to show relationships. For example, "Sales *by* region."
* **Try Different Ways:** If a question doesn't work, try phrasing it differently.

<Tip>
  Providing context is crucial when interacting with WisdomAI. The more relevant information you give, the better and more accurate your answers will be. For more insights on how to leverage context effectively, be sure to read the related article [Enhancing Data Analysis with Custom Business Knowledge](/improve-wisdom-ai-responses/enhancing-data-analysis-with-custom-business-context).
</Tip>

### Chat with WisdomAI

1. Navigate to the **Search** window in the left sidebar. The Chat page will open.
2. **Send a question** to the chat.
3. The chat will start preparing the answer. You will be able to see its **Workstream**:
   * The tool (tabular data or textual) selected,
   * The step-by-step process,
   * Any join constraint validation,
   * The final query.

Once it's ready, it will send you the **answer**, typically, in chart format.

<img alt="Image showing the chat" />

## Use filters for better focus

Filters help you narrow down your data to exactly what you need.

* **Set Conditions:** Don't just ask for "customers"; ask for "customers in the US" or "customers who spent over \$500."
* **Use Comparisons:**
  * **Equal:** `where Region is 'North'`
  * **More/Less:** `where Sales > 1000`
  * **Range:** `where Date between '2024-01-01' and '2024-03-31'`
  * **Contains:** `where Product Name contains 'Pro'`
* **Combine Filters:** Use "and," "or," and "not" for more detailed questions. For example, "Sales where Product Category is 'Apparel' AND Region is 'West'."
* **Exclude Things:** Sometimes it is easier to say what you don't want. For example, "All customers except those in California."

### Add or adjust filters

After WisdomAI provides you with the answer, you will be able to:

1. See the **applied filters**, according to your question, e.g., Stage Label, Dates, etc.
2. **Add one or more filters**, such as Lead Source. Here, you also have the option to **clear all filters**.

<img alt="Image showing the Add Filters option" />

## Plan for follow-up questions

One question rarely gives the whole picture. Think about what you'll ask next to dig deeper.

* **Start Broad, Then Detail:** Begin with a general question, then ask for more specifics.
  * *First:* "What were our total sales last quarter?"
  * *Next:* "Which products sold the most?"
  * *Then:* "How did our top product sell over the last year?"
* **Explore Surprises:** If something looks odd, ask why.
  * *Problem:* "Sales in one area dropped last month."
  * *Ask:* "What marketing happened there?" or "Were there many returns?"
* **Compare Things:** Look for differences and similarities.
  * *Question:* "How do costs in Q1 compare to Q2?"
  * *Ask:* "What caused that difference?"
* **Look at Different Angles:** If you are looking at sales by area, next look at sales by product or by customer.

<img alt="Follow Up Question Pn" />

## Use business terms Set by Admins

Your organization has a shared language for its data. Using these official terms is key.

* **What are Business Terms?**
  * They are the **official words** your company uses.
  * They define what "Customer," "Revenue," or "Active User" **really mean** for your business.
  * **Admins** usually create and manage them, often in a **business glossary**.
* **Why Are They Important?**
  * **Everyone Understands:** Ensures everyone means the same thing by "Sales."
  * **Correct Answers:** Prevents mistakes and helps you query the right data.
  * **Save Time:** Less time spent explaining terms.
  * **Trust Your Data:** When terms are clear, data is more reliable.
  * **Better Questions:** Helps you use the exact words WisdomAI understands.
* **How to Use Them:**
  * **Check Your Company's Glossary:** Always look up terms there first.
  * **Use Exact Words:** If "Sales" is officially "Total Recognized Sales (USD)," use that.
  * **Understand What's Behind It:** Even if you don't use database names, knowing how a term like "Active Customer" is defined (e.g., active in the last 90 days) helps you ask better questions.
  * **Ask if Unsure:** If a term is unclear, ask your data team. This helps everyone.
  * **Help Others:** Encourage colleagues to use the standard terms, too.

By following these steps, you will ask stronger questions and get more meaningful insights from your data.

## Next steps

<CardGroup>
  <Card title="Advanced Data Modeling" icon="sitemap" href="/setting-up-wisdom-ai/advanced-data-modeling-creating-context">
    Define relationships and context in your data to enable more powerful analysis.
  </Card>

  <Card title="Validate and Test Answers" icon="check-double" href="/improve-wisdom-ai-responses/validate-and-test-answers">
    Understand the methods for verifying the correctness and reliability of generated answers.
  </Card>

  <Card title="Provide Feedback to the System" icon="thumbs-up" href="/setting-up-wisdom-ai/feedback-mechanisms/provide-feedback-to-the-system">
    Learn how to rate answers and provide corrections to improve the system's accuracy.
  </Card>

  <Card title="Turn Answers into Dashboards" icon="book-open" href="/using-wisdom-ai-everyday/turn-answers-into-dashboards">
    Compile key insights and visualizations into a shareable, narrative-driven report.
  </Card>
</CardGroup>


# Auditing
Source: https://docs.wisdom.ai/using-wisdom-ai-everyday/auditing



Effective auditing ensures that your team always has access to trusted, up-to-date information, thereby boosting productivity, supporting faster decision-making, and reducing duplicated work. Follow this guide to implement a scalable auditing process using three key actions:

* [Tag Chats](#tag-chats) to organize and find key insights quickly.
* [View and Navigate the Chat History](#view-and-navigate-the-chat-history) to surface trusted information.
* [Share Vetted Answers](#share-vetted-answers-from-the-chat) to scale knowledge across your team.

## Tag chats

You can organize and categorize your conversations by renaming them. This action enables you to assign descriptive titles that act as tags, making it easier to filter and search for specific topics or keywords across your chat history.

To tag a chat:

1. Navigate to the **Chats** section in the left sidebar and click on it to view your active chat list.
2. In the **Chats list**, find the specific chat you intend to categorize.
3. Click the **kebab menu** (three dots), found to the right of the chat's current title in the list, and select the **Rename** option.
4. The text field becomes active and displays the current chat name, such as “Calculate revenue from won sales by close date.” Type a new, descriptive **name** into this field or add any relevant **keywords** that clearly reflect the chat's topic or project. For example, you might rename it to "Revenue Analysis - Won Sales Trends" or "FC Sales - Q1 2025 Revenue Calculation." This new name works as a tag that helps categorize the conversation.

<Tip>
  When renaming chats, use consistent keywords as tags to make search results more reliable and structured. This will serve to filter by keywords in the [Chat Log](#view-and-navigate-the-chat-history).
</Tip>

5. After entering the new name or introducing the tag, click the **Confirm** button located next to the input field.

<Note>
  If you decide not to proceed with the renaming, click the **Go Back** button.
</Note>

<img alt="Image showing the chat section and the rename it modal" />

Once confirmed, the chat will be updated with its new name, which will also be reflected in the Chat Log. This change will enhance its discoverability when using the **Filter by summary** option or other search functionalities to locate chats by their assigned categories.

<img alt="Image displaying the Filter by summary option within the Chat Log" />

## View and navigate the chat history

The Chat Log helps you review valuable information. You can filter, review, and evaluate past interactions to surface valuable insights, identify feedback loops (positive or negative), and access chats to [refine content like SQL queries](/improve-wisdom-ai-responses/validate-and-test-answers). This visibility supports transparency, enhances content quality, and helps maintain a living repository of trusted, actionable information.

To navigate the Chat Log:

1. Access the **Chat Log**, located in the left sidebar, to open its main interface.
2. View **Chat Log entries**. The Chat Log displays a tabular view of interactions, with each row representing a chat entry and providing key metadata:

   <Tabs>
     <Tab title="Last Message">
       Indicates the date and time of the most recent message within the chat, establishing a precise chronological order.
     </Tab>

     <Tab title="User">
       Identifies the initiating or contributing user for each chat, ensuring clear accountability.
     </Tab>

     <Tab title="Domain">
       Specifies the associated Domain (e.g., "B2B Sales - 1Q25," "Customers"), facilitating organized access to information.
     </Tab>

     <Tab title="Chat">
       Offers a concise overview of the initial query of the interaction or the Chat title.
     </Tab>

     <Tab title="Responses">
       Displays the number of responses within a chat, indicating the depth of the conversation. Accompanying icons provide additional context on interaction types (e.g., if negative feedback has been given or if the answer has limited context).
     </Tab>
   </Tabs>
3. **Filter** and locate **interactions**. You can efficiently locate specific historical interactions using various filtering options to streamline your review process:

   <Tabs>
     <Tab title="Date Range">
       Use Start Date and End Date fields to constrain the view to a specific timeframe, allowing for targeted historical review.
     </Tab>

     <Tab title="User-Specific">
       Filter by user to display only chats associated with a particular team member, enabling focused review of individual contributions.
     </Tab>

     <Tab title="Domain-Specific">
       Restrict entries to a selected Domain, facilitating the review of Domain-specific discussions.
     </Tab>

     <Tab title="Filter by summary">
       Search for specific keywords or phrases within chat summaries, including any tags or descriptive titles you have previously added. This improves discoverability and ensures your team can quickly locate curated content by keywords, topic, or project focus.
     </Tab>

     <Tab title="Clear Filters">
       Use this button for quick removal of all active filters, restoring the full log view.
     </Tab>
   </Tabs>

<img alt="The Chat Log interface is displayed showing a list of chats with metadata like user, domain, and number of responses" />

4. Access the detailed chat history to obtain a complete understanding of any interaction's progression and context. Click the **View details** button corresponding to any chat entry to open a dedicated view or modal containing the full chat transcript. Here, you can:

   * **Review Full Conversations:** The detailed view presents the entire sequence of messages, queries, and responses chronologically. This comprehensive record illustrates the evolution of information and discussions, providing complete context.
   * **Identify User Contributions:** You can see who said what, which helps with accountability and tracking the source of each idea.
   * **Explore Data Drill-Downs:** The detailed view provides clickable links to associated data, allowing direct access and deeper examination of underlying metrics and complete datasets relevant to the specific conversation.

   <img alt="View Details window displayed" />

## Share vetted answers from the chat

The Chat Log also allows you to open your past chat windows and share these interactions with other users or your entire organization. This ensures that valuable, vetted responses are easily disseminated and accessible.

Follow these steps to share vetted answers from the Chat Log:

1. Access the **Chat Log**, choose an **interaction** from the list, and click on **View Details**.
2. Locate and click on the specific **chat entry** that contains the vetted answer you wish to share. This action opens a detailed view of that particular data from the conversation.

<img alt="The share vetted answers interface is displayed" />

3. Within the detailed chat view, locate and click on the **Share icon** (represented by three connected dots) in the top right corner of the chat window.
4. A Share-chat modal will appear, allowing you to configure who can access the shared content. Configure **Sharing Permissions**:

   <AccordionGroup>
     <Accordion title="Select Specific Users">
       * Click the **Select users to share with** dropdown menu.
       * **Type** the **name**(s) of individual users you want to share with and **select** them from the list.
       * Currently, your name may be listed as having access, indicating that you are the owner or creator of this chat.
     </Accordion>

     <Accordion title="General Access Options">
       * **Share with everyone in your organization:** Toggle this switch to allow all members of your organization to view the chat.
       * **Share with anyone:** Toggle this switch to generate a public link that can be accessed by anyone, regardless of whether they are in your organization. Use this option with caution for sensitive information. Obtain a direct **link** to the shared chat by clicking the **Copy link button**. This copies the URL to your clipboard, which you can then paste into emails, messages, or documents.
     </Accordion>
   </AccordionGroup>
5. Once you have configured the desired sharing permissions, click **Done** to share the chat with the selected audience.

<img alt="Sharing options dialog with dropdowns for users, organization toggle, and public link generation" />

## Next steps

<CardGroup>
  <Card title="Advanced Data Modeling" icon="sitemap" href="/setting-up-wisdom-ai/advanced-data-modeling-creating-context">
    Define relationships and context in your data to enable more powerful analysis.
  </Card>

  <Card title="Validate and Test Answers" icon="check-double" href="/improve-wisdom-ai-responses/validate-and-test-answers">
    Understand the methods for verifying the correctness and reliability of generated answers.
  </Card>

  <Card title="Provide Feedback to the System" icon="thumbs-up" href="/setting-up-wisdom-ai/feedback-mechanisms/provide-feedback-to-the-system">
    Learn how to rate answers and provide corrections to improve the system's accuracy.
  </Card>

  <Card title="Turn Answers into Dashboards" icon="book-open" href="/using-wisdom-ai-everyday/turn-answers-into-dashboards">
    Compile key insights and visualizations into a shareable, narrative-driven report.
  </Card>

  <Card title="Enhance Analysis with Business Knowledge" icon="lightbulb" href="/improve-wisdom-ai-responses/enhancing-data-analysis-with-custom-business-context">
    Improve analysis by providing custom business definitions, synonyms, and other contextual information.
  </Card>
</CardGroup>


# Command Palette
Source: https://docs.wisdom.ai/using-wisdom-ai-everyday/command-palette



The command palette is a keyboard-first launcher for WisdomAI. Open it with a single shortcut to jump to any chat, dashboard, domain, connection, or settings page, search across your workspace, or trigger actions like inviting a user or adding a new connection — without leaving the page you're on.

The palette only ever shows entries you have permission to use, so the items in your palette may differ from a teammate's.

## Open the command palette

Press the keyboard shortcut from anywhere in WisdomAI:

* **macOS:** <kbd>⌘</kbd> + <kbd>K</kbd>
* **Windows / Linux:** <kbd>Ctrl</kbd> + <kbd>K</kbd>

Press the same shortcut again, click outside the dialog, or press <kbd>Esc</kbd> to close it.

<Frame>
  <img alt="Image" />
</Frame>

<Tip>
  The shortcut works on every authenticated page. If nothing happens, make sure WisdomAI is the focused tab and that you don't have a system-level shortcut bound to <kbd>⌘</kbd>+<kbd>K</kbd>.
</Tip>

## Layout

When you open the palette, you see:

* A **search input** at the top with the placeholder *Ask or jump to anything...*
* A **list of items** grouped by section. The home view shows: **Quick Actions**, **Browse**, **Users**, **Profile**, and **Help**.
* A **footer** that shows the available keyboard shortcuts for the current view.

After you select a category, a **breadcrumb bar** appears above the search input with a **Back** button so you can return to the home view.

## Search anything

Start typing in the search input to filter across every entry in the palette — chats, dashboards, domains, connections, agents, subscriptions, settings pages, and built-in actions.

WisdomAI uses fuzzy matching, so typos and partial words still surface relevant results. Each entry is also indexed by its keywords; typing `sso` finds **Single Sign-On (SSO)**, `embed` finds **Embedded Mode**, and so on.

Results are ordered by relevance:

1. **Exact name matches** appear first.
2. **Quick Actions** (such as **New Chat**) and **direct navigation** entries (such as **Dashboards** or **Domains**) come next.
3. **Action items** (entries marked with the **Action** badge) follow.
4. **Items whose names start with your query** are then prioritized over partial matches.
5. **Other fuzzy matches** appear at the bottom.

When a result lives inside a category — for example, a specific dashboard — the palette shows a small *in \<Category>* hint below its name so you know where it came from.

<Frame>
  <img alt="Image" />
</Frame>

## Navigate with the keyboard

The footer always shows the shortcuts available in the current view:

| Key                         | What it does                                                                                        |
| :-------------------------- | :-------------------------------------------------------------------------------------------------- |
| <kbd>↑</kbd> / <kbd>↓</kbd> | Move the selection up or down.                                                                      |
| <kbd>Enter</kbd>            | Open the highlighted item or run the highlighted action.                                            |
| <kbd>Backspace</kbd>        | Return to the previous view (only shown when you're inside a category and the search box is empty). |
| <kbd>Esc</kbd>              | Close the palette.                                                                                  |

You can also click any entry with the mouse.

## Browse by category

The **Browse** section on the home view lists the major areas of WisdomAI. Selecting one opens its submenu, which contains the actions you can run there plus a live list of items you have access to.

The categories the palette can show are:

| Category          | What you'll find                                                            |
| :---------------- | :-------------------------------------------------------------------------- |
| **Chats**         | Your recent conversations. Selecting one opens the chat.                    |
| **Agents**        | The **Add Agent** and **View All Logs** actions, plus your existing agents. |
| **Dashboards**    | The **Add Dashboard** action, plus dashboards you can view.                 |
| **Domains**       | The **Add Domain** action, plus domains you have access to.                 |
| **Connections**   | The **Add Connection** action, plus your data source connections.           |
| **Playground**    | Opens the SQL Playground directly.                                          |
| **Chat Log**      | Opens the Chat Log directly.                                                |
| **Subscriptions** | Your scheduled dashboard and notification subscriptions.                    |
| **Settings**      | All settings pages, listed below.                                           |
| **Organizations** | The **Add Organization** action, plus organizations you can switch into.    |

<Note>
  Categories whose pages don't have a submenu — such as **Playground** and **Chat Log** — navigate directly when you select them. Categories that you don't have permission for, or that aren't enabled for your instance, are hidden from the home view entirely.
</Note>

<Frame>
  <img alt="Image" />
</Frame>

## Run actions

Some entries are **actions** rather than destinations — they are tagged with an **Action** badge in the list. Selecting an action triggers it immediately. Examples include:

* **New Chat**: start a fresh conversation.
* **Add Dashboard**, **Add Domain**, **Add Connection**, **Add Agent**, **Add Organization**: open the relevant create flow.
* **View All Logs** (under **Agents**): jump to the agent run log.
* **Invite Users** (under **Users**): open the invite flow.
* **Sign out** (under **Profile**): sign out of WisdomAI.
* **Customer Portal** (under **Profile**): open the support portal in a new tab.

## Jump to settings

Selecting **Settings** in the **Browse** section reveals every settings page in a single submenu, so you don't have to navigate through the sidebar to reach them. The submenu can include:

* **Single Sign-On (SSO)**
* **API Keys**
* **Connected Apps**
* **Chart Colors**
* **Embedded Mode**
* **Slack Integration**
* **Notifications**
* **Email Access Control**

You can also type a setting's name into the search input from the home view to jump straight to it — for example, typing `email access` highlights the [Email Access Control](/settings/email-access-control) page.

<Tip>
  The palette respects your permissions: each entry only appears if you have access to it. If a setting isn't listed, ask your administrator to grant the relevant role.
</Tip>

## Switch organizations

If your WisdomAI tenant has multiple organizations and you have access to more than one, the **Organizations** category lets you switch contexts without leaving the page. Selecting an organization in the submenu loads it as your active organization and takes you to the search page in that organization.

## Profile and help shortcuts

Two sections at the bottom of the home view give you fast access to account-level actions:

* **Profile** — Open **Profile settings**, jump to the **Customer Portal**, or **Sign out**.
* **Help** — Open the [WisdomAI Documentation](https://docs.wisdom.ai) in a new tab.

## Tips for working faster

<AccordionGroup>
  <Accordion title="Use keywords, not exact names">
    Every entry has a list of keywords attached to it. Typing a related term — `auth` instead of `Single Sign-On`, `iframe` instead of `Embedded Mode`, `add user` instead of `Invite Users` — surfaces the right entry without you having to remember its exact label.
  </Accordion>

  <Accordion title="Stay in a category to narrow your search">
    Open a category first (for example, **Dashboards**), then type your query. The palette restricts results to that category, which is faster than scanning a global search.
  </Accordion>

  <Accordion title="Use the palette to launch creation flows">
    Instead of clicking **+** buttons across multiple pages, type the entity you want to create — `add dashboard`, `add agent`, `add connection` — and run the matching action straight from the palette.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="Ask Better Questions" icon="question" href="/using-wisdom-ai-everyday/ask-better-questions">
    Build sharper natural-language questions to get more accurate answers.
  </Card>

  <Card title="Email Access Control" icon="envelope" href="/settings/email-access-control">
    Configure who can sign in to your WisdomAI instance.
  </Card>

  <Card title="Slack" icon="slack" href="/integrations/connect-to-slack">
    Connect WisdomAI to your Slack workspace.
  </Card>

  <Card title="Schedule Dashboards & Notifications" icon="bell" href="/using-wisdom-ai-everyday/schedule-dashboards-notifications">
    Set up recurring dashboard updates and alerts for your team.
  </Card>
</CardGroup>


# Knowledge Management via GraphQL API
Source: https://docs.wisdom.ai/using-wisdom-ai-everyday/knowledge-management-via-graph-ql-api



WisdomAI provides a GraphQL API for defining and maintaining domain knowledge.

Knowledge entries represent domain-specific terminology and workflows that guide how the system interprets data and generates responses.

### When to use Knowledge management

* **Defining Regional Terms**: For example, establishing that "Regions are Territories."
* **Outlining Sales Stages**: Defining a sequence like "Prospect, Negotiation, Closed."
* **Specifying Contract Types**: Categorizing items such as "Standard, Enterprise, Custom."

<Warning>
  You must have **Data Administrator** rights on the domain to use this API. Only users with this access level can create, update, or delete knowledge items.
</Warning>

## Create Knowledge

Add one or more knowledge items to a domain.

To add knowledge:

1. Use the `addKnowledge` mutation.
2. Provide the `domainId` and your `knowledgeEntries`.

**Mutation:**

```graphql theme={null}
mutation AddKnowledge($domainId: ID!, $knowledgeEntries: [KnowledgeInput!]!) {
  addKnowledge(domainId: $domainId, knowledgeEntries: $knowledgeEntries) {
    id
    name
    knowledge {
      name
      description
    }
  }
}
```

```json Example Request theme={null}
{
  "domainId": "abc-123-def",
  "knowledgeEntries": [
    {
      "name": "Regional Terms",
      "description": "Regions are Territories"
    },
    {
      "description": "Sales stages: Prospect, Negotiation, Closed"
    }
  ]
}
```

<Note>
  * `description` is required; `name` is optional.
  * Duplicate knowledge (identified by the description) is automatically filtered out.
  * You can add multiple items in a single request.
</Note>

## Read Knowledge

Retrieve all knowledge items currently associated with a domain.

To retrieve knowledge:

1. Execute the `GetDomainKnowledge` query.
2. Input the relevant `domainId`.

**Query:**

```graphql theme={null}
query GetDomainKnowledge($domainId: ID!) {
  zSheet(id: $domainId) {
    id
    name
    knowledge {
      name
      description
    }
  }
}
```

```json Example Request theme={null}
{
  "domainId": "abc-123-def"
}
```

```json Example Response theme={null}
{
  "data": {
    "zSheet": {
      "id": "abc-123-def",
      "name": "Sales Domain",
      "knowledge": [
        {
          "name": "Regional Terms",
          "description": "Regions are Territories"
        },
        {
          "name": null,
          "description": "Sales stages: Prospect, Negotiation, Closed"
        }
      ]
    }
  }
}
```

## Update Knowledge

Modify an existing knowledge item. You must provide the exact original description to identify which item to update.

To update an item:

1. Identify the `oldKnowledge` entry using its exact description.
2. Define the `updatedKnowledge` with your new values.

**Mutation:**

```graphql theme={null}
mutation UpdateKnowledge(
  $domainId: ID!
  $oldKnowledge: KnowledgeInput!
  $updatedKnowledge: KnowledgeInput!
) {
  updateKnowledge(
    domainId: $domainId
    oldKnowledge: $oldKnowledge
    updatedKnowledge: $updatedKnowledge
  ) {
    id
    knowledge {
      name
      description
    }
  }
}
```

<Warning>
  **Important:** The exact knowledge description must match what is currently in the system. If the knowledge has been modified since it was last read, the update will fail.
</Warning>

```json Example Request theme={null}
{
  "domainId": "abc-123-def",
  "oldKnowledge": {
    "description": "Sales stages: Prospect, Negotiation, Closed"
  },
  "updatedKnowledge": {
    "name": "Sales Pipeline",
    "description": "Sales stages: Lead, Prospect, Negotiation, Closed, Lost"
  }
}
```

## Delete Knowledge

Remove a knowledge item from a domain.

To delete an item:

1. Provide the `domainId`.
2. Provide the exact description of the item you wish to remove.

```graphql theme={null}
mutation DeleteKnowledge($domainId: ID!, $knowledge: KnowledgeInput!) {
  deleteKnowledge(domainId: $domainId, knowledge: $knowledge) {
    id
    knowledge {
      name
      description
    }
  }
}
```

```json Example Request theme={null}
{
  "domainId": "abc-123-def",
  "knowledge": {
    "description": "Regions are Territories"
  }
}
```

<Warning>
  **Important:** You must provide the exact knowledge description. If it does not match exactly, the deletion will fail.
</Warning>

## Common scenarios

Below are typical workflows for maintaining and restructuring domain knowledge.

### Bulk import Knowledge

You can add multiple knowledge items at once by listing them within the `knowledgeEntries` array.

**Mutation**:

```graphql theme={null}
mutation {
  addKnowledge(
    domainId: "abc-123-def"
    knowledgeEntries: [
      { description: "Item 1" }
      { description: "Item 2" }
      { name: "Named Item", description: "Item 3" }
    ]
  ) {
    knowledge {
      name
      description
    }
  }
}
```

### Replace all Knowledge

To completely refresh a domain's knowledge base:

1. **Query** the domain to retrieve all current knowledge items.
2. **Delete** each item individually using the delete mutation.
3. **Add** the new set of knowledge items.


# Create and Manage Prompt Templates
Source: https://docs.wisdom.ai/using-wisdom-ai-everyday/prompt-templates



Prompt templates allow you to turn successful queries into reusable building blocks for other users. Instead of starting from scratch, Explorers can use these templates to run complex analyses quickly.

## How prompt templates creation works

A prompt template starts as a normal chat interaction. When a response is [reviewed](/setting-up-wisdom-ai/feedback-mechanisms/reviewed-queries) and confirmed as useful, it can be converted into a reusable template.

This conversion is manual. An admin must explicitly enable the **Parameterized** toggle to turn the reviewed response into a prompt template.

After a template is created, WisdomAI automatically organizes it. The system assigns the template to a **Topic**, which is simply a category used to group similar templates together. These topics are displayed as cards on the domain chat page, helping users discover relevant prompts.

<img alt="GIF showing how to review a response and enable the Parameterized toggle to create a prompt template." />

## Autocomplete

Autocomplete uses existing prompt templates to suggest relevant queries as users type. It is domain-specific, meaning suggestions are generated only from prompts created within the current domain.

When a user starts typing in the main chat window, WisdomAI searches the Prompt Gallery (if available) and displays matching prompts as clickable autocomplete suggestions.

## Next steps

<CardGroup>
  <Card title="Advanced Data Modeling" icon="sitemap" href="/setting-up-wisdom-ai/advanced-data-modeling-creating-context">
    Define relationships and context in your data to enable more powerful analysis.
  </Card>

  <Card title="Provide Feedback to the System" icon="thumbs-up" href="/setting-up-wisdom-ai/feedback-mechanisms/provide-feedback-to-the-system">
    Learn how to rate answers and provide corrections to improve the system's accuracy.
  </Card>

  <Card title="Understand Domains" icon="sliders" href="/setting-up-wisdom-ai/manage-domains/understand-domains">
    Manage and customize your data domains to refine context and improve query results.
  </Card>
</CardGroup>


# Request Help from Admin
Source: https://docs.wisdom.ai/using-wisdom-ai-everyday/request-help-from-admins



The Request Help from Admin feature allows end-users to flag inadequate AI responses and request manual intervention from an administrator. When a user submits a request, the team receives a notification in a configured Slack channel containing the context needed to resolve the issue.

## Before you begin

Make sure you have a Slack workspace integrated with your account. See the [Connect to Slack](/integrations/connect-to-slack) page.

## Configure the Admin Help Channel

Configuration is managed at the Organization level. This allows you to route help requests from different workspaces to different Slack channels.

1. In the sidebar, click **Settings**.
2. Select **Notifications** from the settings menu.
3. In the text field, configure the Slack channel where you want to receive requests and click **Save**.

<Frame>
  <img alt="Image showing the Document Tables interface" />

  <img alt="Image showing the Document Tables interface" />
</Frame>

4. A confirmation message, "Slack notification channel saved" will appear in the top-right corner of the screen.

## How to request help

If you received an incorrect or incomplete response from the AI, you can trigger a help request directly from the chat interface.

1. Below the AI response, you can click the "Ask for Help" **headset icon**.

<Frame>
  <img alt="Image showing the help icon" />

  <img alt="Image showing the help icon" />
</Frame>

2. A modal titled **Ask Admin for Help** will appear. You can describe what went wrong (e.g., "This was answered incorrectly").
3. Click **Send Help Request,** and the Admin receives it on the configured channel.

<Frame>
  <img alt="Image showing how to ask admin" />

  <img alt="Image showing how to ask admin" />
</Frame>

4. A confirmation message, "Help request sent to admin" will appear in the top-right corner of the screen.

## Admin notification

Once submitted, the Slack notification appears in the configured channel as follows:

```text theme={null}
{User Name} requires assistance on conversation: (Link to Conversation)
{User message}: This was answered incorrectly.
```

## Next steps

<CardGroup>
  <Card title="Connect to Slack" icon="slack" href="/integrations/connect-to-slack">
    Learn how to connect WisdomAI to Slack.
  </Card>

  <Card title="Validate and Test Answers" icon="check" href="/improve-wisdom-ai-responses/validate-and-test-answers">
    Learn how to improve WisdomAI responses.
  </Card>
</CardGroup>


# Subscribe to a Dashboard
Source: https://docs.wisdom.ai/using-wisdom-ai-everyday/schedule-dashboards-notifications



By subscribing to receive notifications, recipients can automatically get updates, such as reminders or content deliveries via email.

Use notifications to:

* Keep stakeholders in the loop.
* Ensure timely reviews or approvals.
* Automate regular Dashboard updates without manual follow-up.

Follow this guide to learn how to schedule Dashboards.

## Receive Dashboard updates

1. Navigate to the **Dashboards** section in the left sidebar.
2. Find the Dashboard you would like to share, click on the kebab menu icon, and select **Subscribe**.

<img alt="Schedule Dashboard Notifications" />

3. In the modal window that opens, you can create a new notifications schedule by configuring the following:
   * **When?**
     * Set the **Start Date**, for example, to 31/05/26 at 9:00 AM.
     * Choose the **Interval**, for example, Repeat every 2 Weeks.
   * **What?**
     * Select the **Delivery Method** (currently, only **email** is supported).
     * Enter the **recipient’s email address**. You can add more than one address by separating them with a comma.
4. Click on **Create** to save your scheduled notification.

<img alt="Schedule Dashboard Notifications" />

<Note>
  **Existing subscriptions**

  After subscribing to a Dashboard, it will appear in the **Existing subscriptions** section the next time you open the **Subscribe** option for the same Dashboard. From there, you can **Test** or **Remove** it.

  <img alt="Existing Schedules" />
</Note>

Here is an example of how notifications from WisdomAI are delivered: users receive a summary email containing key insights, a visual trend graph, and specific data points, as illustrated in the image below.

<img alt="Notification Email" />

## Next steps

<CardGroup>
  <Card title="Turn Answers into Dashboards" icon="book-open" href="/using-wisdom-ai-everyday/turn-answers-into-dashboards">
    Compile key insights and visualizations into a shareable, narrative-driven report.
  </Card>

  <Card title="Share Dashboards and Set Access Control" icon="share-nodes" href="/using-wisdom-ai-everyday/share-dashboards-and-set-access-control">
    Learn how to share your dashboards with others and manage who can view or edit them.
  </Card>
</CardGroup>


# Share Dashboards and Set Access Control
Source: https://docs.wisdom.ai/using-wisdom-ai-everyday/share-dashboards-and-set-access-control



You can share Dashboards with your entire team or grant access to specific users. Use the sharing option to:

* Collaborate across teams.
* Ensure key stakeholders have access to relevant, real-time data.
* Control who can view and interact with each Dashboard.

Follow this guide to learn how to share Dashboards.

## Share a Dashboard and control access

1. Navigate to the **Dashboards** section in the left sidebar.
2. Find the Dashboard you would like to share, click on the kebab menu icon, and select **Share**.

<Frame>
  <img alt="Share Dashboard" />
</Frame>

<Tip>
  You can also share the Dashboard you are working on by clicking on the Share icon in the toolbar.

  <Frame>
    <img alt="Share from Dashboard" />
  </Frame>
</Tip>

3. In the modal window that opens, you can choose from the following options:

* **Select users to share with**. In this case, only those specific users will gain access to view the Dashboard.
* Set a **General Access**. In this case, you can enable any of the following options :
  * **Share your Dashboard with everyone in your organization** so all members have access.
  * Share the provided **link** with anyone who needs access to the Dashboard.

4. Click **Done** to save your changes.

<img alt="Share Dashboard" />

## Next steps

<CardGroup>
  <Card title="Turn Answers into Dashboards" icon="book-open" href="/using-wisdom-ai-everyday/turn-answers-into-dashboards">
    Transform key insights and visualizations into a clear, shareable dashboard.
  </Card>

  <Card title="Schedule Dashboard Notifications" icon="calendar-days" href="/using-wisdom-ai-everyday/schedule-dashboards-notifications">
    Automate notifications to keep stakeholders informed with the latest dashboard updates.
  </Card>
</CardGroup>


# Turn Answers into Dashboards
Source: https://docs.wisdom.ai/using-wisdom-ai-everyday/turn-answers-into-dashboards



Dashboards provide a centralized view of your key business metrics and data visualizations, transforming individual responses into a live reporting hub. You can create Dashboards directly from Chat Responses or from the Dashboard Editor interface. With Dashboards, you can:

* Create dynamic narratives using your data.
* Customize layouts and visuals from responses to suit your audience.
* Share updates that **automatically reflect the changes** in your datasets.

Follow this guide to start building Dashboards and communicate insights clearly and effectively.

## Create Dashboards from chat responses

1. Within your chat window, click on the contextual menu icon labeled "In this chat."
2. Select one or more **answers** that you would like to include in your Dashboard.

<Tip>
  Click **Select all** to add all the chat responses at once.
</Tip>

3. Click on **Add to dashboard**.

<Frame>
  <img alt="NEW UI Add To Dashboard01" />
</Frame>

4. In the modal window that opens, type the **title** of the new Dashboard or select an existing one.
5. Click the **Add to Dashboard** button. Now, you can find it under the **Dashboards** tab in the sidebar to begin sharing insights or scheduling updates.

<Frame>
  <img alt="NEW UI Add To Dashboard02" />
</Frame>

## Create Dashboards from the Editor

1. Open **Dashboards** in the left sidebar.
2. Click on the **Add Dashboard** button.

<Frame>
  <img alt="Create Dashboards from the Dashboard Editor" />
</Frame>

3. Add a relevant **name** to your Dashboard.
4. Click on **Create Dashboard**.

<Frame>
  <img alt="Create Dashboards from the Editor" />
</Frame>

5. The **Add visualization widget** modal window will open. In this window, you can ask WisdomAI a question about your data in natural language. Based on your question and query, WisdomAI may generate a visual representation, such as a chart or graph, that you can review and add directly to the Dashboard.
6. Click on the **Add latest visualization as a widget** button to save the response (a chart in this example) in the Dashboard.

<img alt="Create Dashboards from the Dashboard Editor" />

Your Dashboard has now been created and saved. You can find it within the Dashboards tab.

<Frame>
  <img alt="Dashboards view" />
</Frame>

## Next steps

<CardGroup>
  <Card title="Schedule Dashboard Notifications" icon="calendar-days" href="/using-wisdom-ai-everyday/share-dashboards-and-set-access-control">
    Set up automated notifications to keep stakeholders updated with the latest dashboard insights.
  </Card>

  <Card title="Share Dashboards and Set Access Control" icon="share-nodes" href="/using-wisdom-ai-everyday/share-dashboards-and-set-access-control">
    Learn how to share your dashboards with others and manage who can view or edit them.
  </Card>
</CardGroup>


# Work with CSV Files
Source: https://docs.wisdom.ai/using-wisdom-ai-everyday/work-with-csv-files



With WisdomAI, you can integrate and analyze data stored in **CSV**, **TSV**, or **Excel** files. Depending on your goals and permissions, there are three distinct ways to work with these files:

1. [Add Data to a Domain (Admins)](#1-add-data-to-a-domain-admins)
2. [Create a Private Domain (Admins)](#2-create-a-private-domain-admins)
3. [Attach CSV as a Chat File (Admins/Explorers)](#3-attach-csv-as-a-chat-file-adminsexplorers)

## 1. Add data to a Domain (Admins)

Admins can add new CSV files as tables or replace existing tables within a shared domain. This change affects the domain-level schema, meaning every Explorer assigned to that domain can query this data. Use this option to make a dataset available to your entire team.

Follow the steps below to add data to a domain:

1. Navigate to **Domains** and select your target domain.
2. Click the **Data Sources** tab.
3. Click **Add Table** > **from CSV file**.

<img alt="Create Table From Csv Domain01" />

4. The domain will come set by default, while you will be able to select the **Table Operation**:
   * **Add as a new CSV Table**: Creates a fresh table within the selected domain.
   * **Replace an existing CSV Table**: Updates the data of a specific table while preserving settings.
5. If replacing data, select the specific table to be replaced from the **Select table to replace** dropdown.

   <img alt="Upload CSV dialog with 'Replace an existing CSV table' selected, a dropdown to choose the table to replace, and a confirmation state indicating the CSV file is ready for upload" />
6. Drag and drop your file into the upload area or click to browse.
7. Click **Continue**.

<img alt="Upload Csv 0401" />

8. **Configure Columns**: Review the detected column types (e.g., String, Integer). You can unmark the checkboxes to exclude specific columns from the upload.
9. Click **Preview**.

<img alt="Upload Csv 09" />

10. Ensure the data in the preview grid maps correctly. Click **Create table** (or **Replace table** if updating an existing one).

<Info>
  **Data Replacement Behavior**

  When you replace an existing CSV table, the system updates only the raw data. All existing column descriptions, settings, and domain configurations remain intact, only the table data itself is replaced.
</Info>

<img alt="Upload Csv 10" />

## 2. Create a private Domain (Admins)

Admins can create their own domains by uploading a file. These domains are private by default, and no other user can see them unless the creator explicitly shares them. This method is great for one-off analysis or testing a dataset before sharing it.

Follow the steps below to create a domain from the domain switcher:

1. Navigate to the **homepage**.
2. Click the **domain switcher**.
3. Select the **Upload CSV file...** option.

<img alt="Image showing the Upload CSV option" />

4. In the **Upload CSV or TSV file** modal that opens, leave the default option **+ Create a New Domain with this CSV** selected.
5. Upload your files and click **Continue**.

<img alt="Upload CSV modal window with the Continue button highlighted" />

6. The **Preview CSV file** modal window opens. Click **Configure columns** to continue.

<img alt="Preview CSV file modal window with the Configure columns button highlighted" />

7. The **Configure CSV file** modal opens, displaying a preview of all columns detected in your CSV file.

By default, basic configuration options are shown. To access additional controls, switch the **Show advanced options** toggle **ON** (top-right corner of the modal).

<Tip>
  Check the expandable section below to review all available advanced options and their descriptions.
</Tip>

<Expandable title="Advanced configuration options">
  Advanced options let you control identifiers, ordering, allowed values, and lookup behavior used during analysis.

  * **Primary key**: Marks a column as uniquely identifying each row.
  * **User identifier**: Identifies columns that represent individual users or customers.
  * **Allowed values**: Restricts the column to a defined set of values.
  * **Order allowed values**: Defines a logical order for categorical values.
  * **Default order**: Sets the default sort order for the column.
  * **Enable lookups**: Allows the column to be used for grouping, filtering, and comparisons.

  Review and adjust the column settings as needed.
</Expandable>

8. When you’re done configuring the file, click **Start asking questions**. A chat opens where you can immediately begin querying your data.

<img alt="Upload Csv Method2 03" />

## 3. Attach CSV as a chat file (Admins/Explorers)

You can upload a file directly into a chat session. While the chat still uses your active domain for general context, the AI will prioritize the data in your uploaded file for that specific conversation. This upload method allows you to ask quick questions about a specific file without creating a new domain.

Follow the steps below to attach a file to a chat:

1. Open any Chat.
2. Click the **Attachment (paperclip)** icon in the message bar.
3. Upload your file.

<Tip>
  You can add multiple files and compare them.
</Tip>

4. Ask questions immediately (e.g., "Summarize the trends in this file").

<img alt="Snippet showing the attach files to chat button" />

<Note>
  See [Supported File Types](/improve-wisdom-ai-responses/attach-files-to-chat#supported-file-types) for a complete list.
</Note>

## Next steps

<CardGroup>
  <Card title="Advanced Data Modeling" icon="sitemap" href="/setting-up-wisdom-ai/advanced-data-modeling-creating-context">
    Define relationships and context in your data to enable more powerful analysis.
  </Card>

  <Card title="Validate and Test Answers" icon="check-double" href="/improve-wisdom-ai-responses/validate-and-test-answers">
    Understand the methods for verifying the correctness and reliability of generated answers.
  </Card>

  <Card title="Enhance Analysis with Business Knowledge" icon="lightbulb" href="/improve-wisdom-ai-responses/enhancing-data-analysis-with-custom-business-context">
    Improve analysis by providing custom business definitions, synonyms, and other contextual information.
  </Card>
</CardGroup>