> For the complete documentation index, see [llms.txt](https://docs.riff.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.riff.ai/get-started/quickstart-dashboard-v2-v2.md).
# Build your first app
Go from an idea to a deployed app: describe it, review the plan, connect your data and deploy.
## Before you build — what is an app?
An app in Riff is **a screen your users open**. A dashboard to review data, a form to submit requests, a portal to look something up. You design what people see and how they interact with it. AI can live inside the app as a feature — but humans are in the driving seat.
The mental model: if your project needs a user interface — something people come back to, look at, and use — build an app.
### What makes a good app?
| | Question | Good fit | Not quite |
| ------------------- | ---------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------------- |
| **Interface** | Does this need a screen? | Users need to see data, fill in forms, or make decisions | Nobody needs to look at it — it just runs |
| **Human-led** | Do humans drive the flow? | Users decide what to do based on what they see | The same steps happen the same way every time — that's an agent |
| **Recurring use** | Will people come back to this regularly? | A daily dashboard, a weekly review tool, a lookup portal | A one-off report — just export it |
| **AI as a feature** | Is AI one part of a larger workflow? | A summarisation panel, a search tool, a recommendation widget | AI is doing the whole job unsupervised — that's an agent |
If most of those are a green light, you're in the right place.
### App vs Agent — a quick distinction
Riff gives you two things to build. Knowing which is which saves you time.
**Build an App** when humans drive the flow, the output is a screen someone opens, or AI is a feature inside a larger workflow rather than the whole job.
**Build an Agent** when the job has a clear trigger and a clear "done" state, runs repeatedly, and humans only need to review exceptions — not every step.
Many projects combine both — an agent does the routine work in the background, an app surfaces the results for your team to review.
***
## Building your app
You build in Riff through conversation. Describe what you want, and the Riff agent builds it — connecting to your data and iterating based on your feedback. No forms to fill in, no templates to fight with.
Here's how to get started.
***
## Step 1 — Click New App
From your workspace home, click **New App** in the side navigation.
This opens a conversation in the **Ask Riff** tab. The agent will ask you a series of questions to understand what you're building — who it's for, what data it should show, and what actions users need to take.
Answer as naturally as you'd brief a colleague. Once it has enough to work with, the agent creates a **plan** for your app — the pages it will build, the data it will connect, and the key features it will include.
Review the plan. You can keep refining it in conversation until you're aligned, or tell the agent to go ahead and start building.
{% hint style="info" %}
Spend a moment on the plan before building starts. Iterating on a plan is faster than iterating on a half-built app.
{% endhint %}
***
## Step 2 — Watch it build in Preview
Once building starts, you'll move into the **app builder**. The interface is split: **Preview** on the left, **chat** on the right.
As the agent works, the Preview updates in real time — pages appear, data populates, the layout takes shape. You don't need to do anything while it builds, but you can jump in at any point with feedback.
At the top of the builder you'll find three tabs:
**Preview** — Your app running as you build it. This is your main view as the agent builds. If something looks wrong, paste a screenshot into the chat and tell the agent what to fix.
**Tasks** — The agent's plan converted into a focused task list. This is how you can see exactly what the agent is working on and what's coming next. If a build is taking longer than expected, check here first.
**Automations** — Where scheduled tasks live. This is where you'll see any jobs the app runs on a schedule — such as pulling data from an integration or running an AI workflow at a set time of day.
{% hint style="info" %}
Not sure if the agent understood what you wanted? Ask it to describe its plan and wait for your go-ahead before it starts building — a useful sense-check before it dives in.
{% endhint %}
***
## Step 3 — Connect your data
At some point the agent will ask where your data comes from. You have a few options depending on your setup.
**Integrations** — If your data lives in another system, such as your accounting system or ERP, it can be connected as an integration. See [Integrations](/reference/shared/integrations.md).
**Database** — Riff has a built-in database. Upload a CSV or Excel file to get started, or connect an existing database. The agent handles the rest.
{% hint style="info" %}
Start with what you have. A CSV upload gets you a working app in minutes. You can switch to a live data connection later without rebuilding.
{% endhint %}
***
## Step 4 — Iterate until it's right
Building in Riff is iterative. Keep the conversation going — ask for changes, add screens, adjust layouts. Some useful prompts to keep in mind:
* *"Add a filter for \[field]"*
* *"Show this as a chart instead of a table"*
* *"Make this column sortable"*
* *"Add a second page for \[topic]"*
* *"The data on this panel is wrong — it should show \[X]"*
Be specific. The more clearly you describe what you want, the faster the agent gets there. Using screenshots also improves the agen't ability to understand your needs.
***
## Step 5 — Deploy
When you're happy with how the app looks and behaves, click **Deploy** in the top right.
For a full walkthrough of the deployment process, see [Deploying your app](/reference/app-builder/deploy.md).
***
## You're ready to build
That's the shape of a Riff app: a plan, a data source, a live preview, and a deploy. The app you just built isn't finished — it's a starting point. The best apps grow through use: your team opens it, tells you what's missing, and you add it in.
Keep the conversation with the Riff agent going. The more specific you are about what you want, the faster it gets there.
---
# 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://docs.riff.ai/get-started/quickstart-dashboard-v2-v2.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.
