Quickstart

Quickstart

Get from zero to your first AI-powered retail query in under 5 minutes.

Start the API

# Clone and enter the repo
cd packages/api
 
# Start Postgres + Redis
docker-compose up -d db redis
 
# Install dependencies
pip install poetry && poetry install
 
# Run migrations
alembic upgrade head
 
# Start the API
uvicorn src.main:app --reload

The API is now running at http://localhost:8000. Check the health endpoint:

curl http://localhost:8000/health
# {"status":"ok","version":"0.1.0"}

Create an API key

curl -X POST http://localhost:8000/v1/auth/keys \
  -H "Content-Type: application/json" \
  -d '{"name": "my-first-key"}'
{
  "id": "...",
  "name": "my-first-key",
  "key": "rm_live_AbCdEfGhIjKl...",
  "key_prefix": "rm_live_AbCd",
  "is_test": false,
  "created_at": "2026-04-02T10:00:00Z"
}

Save the key value — it’s shown only once.

Connect a data source

curl -X POST http://localhost:8000/v1/sources \
  -H "Authorization: Bearer rm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Store DB",
    "type": "postgresql",
    "credentials": {
      "host": "db.example.com",
      "port": 5432,
      "database": "retail",
      "username": "readonly_user",
      "password": "secret"
    }
  }'

Note the id returned — this is your source_id.

Configure an AI provider

curl -X POST http://localhost:8000/v1/ai-providers \
  -H "Authorization: Bearer rm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GPT-4o",
    "provider_type": "openai",
    "model": "gpt-4o",
    "api_key": "sk-...",
    "is_default": true
  }'

Sync the schema

curl -X POST http://localhost:8000/v1/sources/{source_id}/sync \
  -H "Authorization: Bearer rm_live_..."

This runs schema discovery in the background. Poll the job until status: "completed":

curl http://localhost:8000/v1/jobs/{job_id} \
  -H "Authorization: Bearer rm_live_..."

Ask your first question

curl -X POST http://localhost:8000/v1/query \
  -H "Authorization: Bearer rm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": "src_...",
    "question": "What were the top 5 products by revenue last month?",
    "options": {
      "include_sql": true,
      "include_chart": true
    }
  }'

You get back: a natural language answer, the generated SQL, the raw data, and chart-ready JSON.

IntroductionAuthentication