> For the complete documentation index, see [llms.txt](https://help.tellius.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.tellius.com/tellius-6.4/kaiya/kaiya-apps/how-to-create-a-kaiya-app.md).
# How to create a Kaiya App
Create a Kaiya App in a Kaiya conversation: start from a request, a question or a data connection, let Kaiya build and check it, refine it, publish it and turn it into a Mission.
An App is built in the same conversation as the analysis behind it. You describe what you need, and Kaiya plans the App, builds it and checks it. The App opens in a panel beside the conversation, so you can see each change as it happens.
You can start from a question you already asked, from an analysis you already ran, or from a goal with nothing more than a data connection. This page walks through the whole flow, from the first request to a published App. For the **Plan** and **Analysis** tabs, the plan review and the version menu, see [Plans and versions in Kaiya Apps](https://help.tellius.com/kaiya/kaiya-apps/plans-and-versions-in-kaiya-apps).
{% hint style="info" %}
**Coming from an earlier release?** In releases before Tellius 6.4, you created an App with **Create App** under a Deep Insights answer, or with **Create New App** on the Apps page, and approved an **App Blueprint** before Kaiya built it. In Tellius 6.4, both paths lead to a Kaiya conversation, and the plan review takes the place of the blueprint. An App built in an earlier conversation keeps that conversation: open the App and select **Open app assistant** to continue it. See [Apps built before Tellius 6.4](https://help.tellius.com/kaiya/kaiya-apps/apps-built-before-tellius-6-4).
{% endhint %}
{% hint style="info" %}
**When Kaiya Conversational AI is off.** In Tellius 6.4, an App is built in a Kaiya conversation. When an administrator turns off **Kaiya Conversational AI** for the workspace (**Settings → Intelligence → Kaiya & AI → Kaiya Configuration**), **Create New App** is hidden on the Apps page, both in the header and on an empty list, and the Apps page tour is skipped. Users in a Kaiya embed session keep **Create New App**.
{% endhint %}
### **In this section**
* [Connect data while building an App](https://help.tellius.com/kaiya/kaiya-apps/how-to-create-a-kaiya-app/connect-data-while-building-an-app): connect a new data source from the conversation, and choose whether the App's data is live.
* [Refine and publish a Kaiya App](https://help.tellius.com/kaiya/kaiya-apps/how-to-create-a-kaiya-app/refine-and-publish-a-kaiya-app): ask for changes, publish the App, turn it into a Mission and come back to it later.
### **Ways to start an App**
* **From the home page.** Select the **App** tag below the ask box and describe the App you want.
* **From an answer.** When an answer is worth keeping, ask Kaiya for an App, or select an App action under **ACTIONS**.
* **From the Apps page.** Select **Create New App**.
* **From an existing App.** Open the App and select **Open app assistant**, the chat icon at the left of the **Plan**, **Analysis** and **App** tabs. The App's own conversation opens with the App beside it.
When you ask Kaiya for an App from a conversation, the App opens in its own conversation in the App builder. That conversation starts with a summary of the context Kaiya carried over. To keep working in the same conversation instead, ask Kaiya to do so.
### **Step 1: Describe the App**
#### **The ask box on the home page**
Below the ask box are four tags: **Deep Insight**, **Mission**, **App** and **Kaiya Architect**. When you select **App**, an **App** chip appears inside the ask box and the hint text changes to **Describe the page**, with an example. Select the **x** on the chip to remove it.
The ask box also holds these controls:
* **Auto detect BV:** Kaiya picks the Business View that fits your request. Open the list to choose a Business View yourself. The list also shows your Kaiya Context Models under **Context models**, next to **Business views**. When both a context model and a Business View fit your request, Kaiya uses the context model. See [Kaiya Context Model](https://help.tellius.com/data/kaiya-context-model).
* **Suggest:** fills the ask box with an example App request built from your data. The ideas under **Popular in your workspace** also change to App ideas. Edit the suggestion or send it as it is.
* **Microphone icon:** speak your request instead of typing it.
* **Send (arrow):** sends your request.
#### **Write the request**
Say who the App is for, the questions it should answer and the measures that matter. For example: *"Create an App for my territories that opens with the top-line prescription numbers for the region, ranks territories by the size of the opportunity, and lets me click into a territory to see its brand-level breakdown and recent weekly movement."*
You don't need to list the charts. Kaiya chooses the sections and the analysis behind each one from what you describe. When Kaiya needs a decision from you, such as which data to use, it asks in the conversation. Each question shows numbered answers to choose from and a box to type your own. Select **Submit** to answer, or **Skip** to leave the question unanswered. You can also press a number key to choose an answer and Enter to confirm.
{% hint style="success" %}
**You don't need to name the type of analysis.** Describe the question the App should answer, such as performance against target or what is driving a change, and Kaiya works out the analysis behind each section. It gets each section's data with SQL steps, and adds Python steps for work that SQL handles less well, such as rankings with ties or shares of a filtered total. When you build an App from an analysis you already ran in the conversation, Kaiya reuses that analysis's queries and Python code as the App's steps. The **Analysis** tab lists the steps.
{% endhint %}
#### **Choose a look**
Kaiya designs each App for its audience and the job they do with it. How much it asks you depends on the size of the App:
* **A larger App.** For an App with several pages or four or more sections, or one built for a team, leadership, customers or the field, Kaiya asks one question before it builds. It offers three design directions fitted to your data and audience. Each one describes what readers see first, the layout and navigation, the look (light or dark, colors and density) and who it suits. A fourth answer, **Choose for me**, lets Kaiya pick and tell you why.
* **A simple App.** For a one-page App with up to three sections built for yourself, Kaiya picks the look on its own. It says in one line what it chose and why, and offers a different look in its follow-up suggestions.
Kaiya keeps the look you chose on every later edit. It changes the look only when you ask, for example *"Use a dark theme"* or *"Make the layout more compact."*
{% hint style="info" %}
**Say the look up front, or compare options?** If you already know how the App should look, such as a dark theme or a compact layout for a meeting-room screen, say so in your request, and Kaiya builds it that way without asking. Leave it out when you'd like to compare a few directions first.
{% endhint %}
### **Step 2: Connect your data from the conversation**
If the data you need isn't connected to Tellius yet, you can connect it without leaving the conversation. Kaiya then builds and checks a Business View on the new data, and builds the App on that Business View. See [Connect data while building an App](https://help.tellius.com/kaiya/kaiya-apps/how-to-create-a-kaiya-app/connect-data-while-building-an-app).
### **Step 3: Review the plan and let Kaiya build**
Before Kaiya builds an App, it shows you the plan: the pages and sections the App will have, and the analysis behind each one. You can approve the plan, ask for a change or cancel. See [Review the plan before a build](https://help.tellius.com/kaiya/kaiya-apps/plans-and-versions-in-kaiya-apps#review-the-plan-before-a-build).
Kaiya builds and updates an App in small steps. A single request can add new parts and change existing ones at the same time. While it works, a status line on its reply shows what it is doing and how many steps it has taken, for example **Saving the app**. The **How Kaiya got this** panel on the reply (named **Thought Process** in earlier releases) shows the steps it takes. Select the arrow on the panel to expand or collapse it.
When the build is done, Kaiya lists what the App includes and tells you that it is saved as a draft, for example **V1 (draft)**. Under the reply:
* **Based on** names the Business View the App was built on.
* An **Open App** card names the App and its version. Select the card to show the App in the panel beside the conversation.
The panel shows the App on its own once Kaiya finishes building it. The **Plan**, **Analysis** and **App** tabs sit under the App's name. The header holds these controls:
* **Version:** lists the App's versions. Each row shows the version number, a **Draft** or **Published** badge, **Active** on the version people see, when it was saved and what changed. Select a row to switch to it.
* **Refresh icon:** refreshes the App's data. It is greyed out while you look at a draft, because a refresh updates the published version.
* **Open full view (expand icon):** opens the App's own page at the version shown in the panel.
* **Close (x):** closes the panel. The conversation stays open.
If the App changes while you have it open, for example when Kaiya saves a new draft, a banner at the top of the panel says so. Select **View latest** to load the newest version.
To see everything the conversation has produced, select the stacked-layers icon in the toolbar on the right edge of the screen. **Artifacts** lists the Apps, Missions and files from this conversation. Select the open icon beside an item to open it.
### **Step 4: Check the App**
Kaiya checks the App the way you see it. After it saves an App, it views the App screen by screen and tab by tab. It looks for blank values, charts that drew nothing, charts that overlap, and content that runs off the page. It corrects what it finds in the same turn. Errors in the App's code are also found and fixed without you having to ask.
If the App preview can't render or can't load its data, a banner says **App preview couldn't render** or **App preview couldn't load data**. Kaiya tries to fix the error on its own a limited number of times. If it still can't, it shows **Unable to automatically resolve this issue.** Select **Fix with Kaiya** on the banner to ask Kaiya to fix it in the conversation. **Fix with Kaiya** works on a draft, or on the active version when the App has no draft. It isn't available to people who can only view the App.
Before you share the App, you can also ask Kaiya to check the numbers. For example: *"Verify every figure in this App."* Kaiya checks each figure, reports any problem it finds and fixes it in the draft.
To see where a number comes from, open the **Plan** tab and read **Data from** on its section, or open the **Analysis** tab. See [Plans and versions in Kaiya Apps](https://help.tellius.com/kaiya/kaiya-apps/plans-and-versions-in-kaiya-apps).
### **Step 5: Refine and publish the App**
Ask Kaiya for changes in plain language, one request or several at a time. Your changes collect in a draft, and people you share the App with keep seeing the published version until you publish again. See [Refine and publish a Kaiya App](https://help.tellius.com/kaiya/kaiya-apps/how-to-create-a-kaiya-app/refine-and-publish-a-kaiya-app), which also covers turning an App into a Mission and coming back to an App later.
### **On Tellius Mobile**
You can also start an App from Tellius Mobile. In the ask box, choose **Build an app**, or select the plus icon at the top of the **Apps** tab, then describe the App. Kaiya builds it in a conversation, the same way as on the web. On an App's page in the mobile app, select **Edit with Kaiya** to keep working on it in its conversation. The build options appear only when your role has full access to Apps and can ask Kaiya. See [Tellius Mobile](https://help.tellius.com/getting-started/tellius-mobile).
### **The message box**
The message box at the bottom of the App conversation holds these controls:
* **Upload File:** attach a file, such as a design image, an HTML prototype or a document that lists your requirements. Any file type can be attached, up to 20 MB per file. The file shows in your message once you send it.
* **Connected apps:** connect the systems Kaiya can read from and write to. See [Tellius as an MCP client](https://help.tellius.com/kaiya/tellius-mcp-server/tellius-as-an-mcp-client).
* **Connect data:** add a data connection from the conversation. See [Connect data while building an App](https://help.tellius.com/kaiya/kaiya-apps/how-to-create-a-kaiya-app/connect-data-while-building-an-app).
* **Business View selector:** shows the Business View the conversation uses. Open it to choose another.
* **Dictate:** speak your message instead of typing it.
* **Send (arrow):** sends your message.
You can stop Kaiya while it is working on a reply. Send your next message to carry on.
### **Best practices**
* **Start with the reader.** Say who will use the App and what they need to decide. Kaiya plans the pages around that.
* **Settle the plan first.** Ask for changes to the plan before you approve a build. Changing the plan is quicker than rebuilding the App.
* **Ask Kaiya to verify the numbers.** Do this before you share the App, and again after a large change.
* **Attach what you already have.** A design image, an HTML prototype or a requirements document gives Kaiya a clear target.
* **Publish working states.** Publish when Kaiya suggests it, so the next change doesn't replace a version that worked.
### **Related pages**
* [Plans and versions in Kaiya Apps](https://help.tellius.com/kaiya/kaiya-apps/plans-and-versions-in-kaiya-apps)
* [Apps built before Tellius 6.4](https://help.tellius.com/kaiya/kaiya-apps/apps-built-before-tellius-6-4)
* [Kaiya Apps](https://help.tellius.com/kaiya/kaiya-apps)
* [Live data in Apps](https://help.tellius.com/kaiya/kaiya-apps/live-data-in-apps)
* [Mastering prompts for Kaiya Apps](https://help.tellius.com/kaiya/kaiya-apps/mastering-prompts-for-kaiya-apps)
* [How to create a Kaiya Mission](https://help.tellius.com/kaiya/kaiya-missions/how-to-create-a-kaiya-mission)
* [Tellius as an MCP client](https://help.tellius.com/kaiya/tellius-mcp-server/tellius-as-an-mcp-client)
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://help.tellius.com/tellius-6.4/kaiya/kaiya-apps/how-to-create-a-kaiya-app.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
