Complete Setup Guide

​

The full journey

​

Step 1: Create your project

1. Go to the Projects section
2. Click Create Project
3. Enter a name (e.g., “Customer Analytics”)
4. Click Create

​

Step 2: Add a connection

1. Open Project settings → Connections in your new project and select your data source from the Connect data cards
2. Choose Try Demo Data to explore with sample data, or connect your real database
3. For real databases, select your database type, enter credentials, and test the connection
4. Click Save

​

Step 3: Create your workspace

1. On your project page, click New workspace
2. Enter a name and select your connection
3. Click Create workspace

1. Select tables — Uncheck tables that aren’t relevant to this agent’s use case
2. Select columns — Uncheck sensitive or irrelevant columns within each table
3. Add descriptions — Annotate tables and columns with plain-English context so the agent understands what the data means, not just what it’s named
4. Mark selectables — Flag categorical columns (region, status, owner) so the agent can enumerate valid filter values at query time

​

Configure data security

1. On the Data Model page, click on a table
2. Go to its Data Security tab
3. Write a filter rule using {{organization.*}} or {{user.*}} placeholders:
   SELECT *
   FROM "orders"
   WHERE "company_id" = {{organization.company_id}}
   
4. Changes autosave to the workspace draft

​

Step 4: Encode your context

• Skills — reusable procedures and conventions the agent loads on demand (Beta)
• Knowledge Base — markdown reference documents (definitions, policies, caveats) searched at chat time
• Memory — per-end-user preference recording, applied automatically in future conversations (Beta)
• MCP as Context Source — live context from external tools and systems

​

Step 5: Test in the Playground

1. Pick a user with the Chatting as picker — the conversation runs under that user’s security rules
2. Ask your most common questions and check the SQL and charts
3. Open the Observability panel on a few responses to confirm the logic is correct

​

Step 6: Publish and go to production

1. Review the draft — changes autosave as you work
2. Click Publish to stage a new workspace version
3. Promote it to production — deployed users and embeds are served the production version

​

Step 7: Create an application

1. Go to the Applications section
2. Click Create Application
3. Enter a name and select the workspace’s data model
4. Click Create

1. Click Add Dashboard in your application
2. Name it and add charts by clicking Add Chart
3. Configure each chart with your data and arrange the layout
4. Click Save

​

Step 8: Add project organizations

1. Go to the Organizations tab
2. Click Add Organization
3. Enter the organization name (e.g., “Acme Corp”)
4. Add properties that your security rules reference:
   {
     "company_id": "acme-123"
   }
   
5. Click Create

​

Step 9: Register end users

​

Via the UI

1. Go to the Users tab
2. Click Add User
3. Enter the user name, select their organization and role
4. Add any user-level properties needed for security rules
5. Click Create

​

Via API

curl -X POST https://api.upsolve.ai/api/v1/project/user/register \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Smith",
    "projectId": "YOUR_PROJECT_ID",
    "userRoleId": "READER_ROLE_ID",
    "projectOrganizationId": "ACME_ORG_ID",
    "properties": {
      "department": "sales"
    }
  }'

​

Step 10: Generate user tokens

curl -X POST https://api.upsolve.ai/api/v1/project/user/token \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "USER_ID_FROM_REGISTRATION",
    "expiration": "24h"
  }'

{
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

​

You’re done!

• Chat with the workspace’s agent using natural language
• View dashboards with their filtered data
• Create their own charts and dashboards in their space

​

Setup checklist

​

Next steps