# Build your first app

## 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.

<figure><img src="/files/dtneh8ywdCVxGKBvIxVr" alt="New app/New agent buttons"><figcaption></figcaption></figure>

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.

<div data-with-frame="true"><figure><img src="/files/0h4pyeUmxaT3wbz3hZmC" alt="App onboarding in the Ask Riff tab" width="563"><figcaption></figcaption></figure></div>

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.

<div data-with-frame="true"><figure><img src="/files/4mWhFWeD6TJ20JCWfb41" alt="" width="478"><figcaption></figcaption></figure></div>

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.

<div data-with-frame="true"><figure><img src="/files/aV3HwPmewNRR52f8QuDQ" alt="" width="563"><figcaption></figcaption></figure></div>

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** — The live running app. 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.

<div data-with-frame="true"><figure><img src="/files/w3n9ywviOsaA9OXSs7iI" alt="" width="563"><figcaption></figcaption></figure></div>

**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? Switch to **Plan mode** in the chat before building starts. The agent will describe what it's going to do without acting — 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 a connected system, open the **+** tab at the top of the builder and select **Integrations**. Connect the system and the agent will use it directly. Riff connects to tools like Google Sheets, Notion, Slack, and ERP systems via API.

**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]"*

<div data-with-frame="true"><figure><img src="/files/TG5ltB5qail7RRiVNEko" alt=""><figcaption></figcaption></figure></div>

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.

<div data-with-frame="true"><figure><img src="/files/W9jk1yhZI2kTnFJc80m0" alt="" width="306"><figcaption></figcaption></figure></div>

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: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.riff.ai/get-started/quickstart-dashboard-v2-v2.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.