Getting started

By the end of this page you'll have search and chat running over your own content, plus a widget you can drop on any page. It takes about ten minutes.

We'll use the command line for the quick path. Every step is also in the admin UI and the HTTP API, shown right alongside.

On this page

• 1. Start the server
• 2. Create an index
• 3. Add your content
• 4. Create an app
• 5. Try it
• 6. Put it on your site
• Running several sites
• Admin at a glance
• Next steps

1. Start the server

If you haven't installed Datalumo yet, do that first. See Installation.

Check it's running:

curl http://localhost:3000/health
# {"status":"ok"}

Then open the admin at http://localhost:3000/admin and sign in with the admin key the installer printed. (If you installed on a server with a domain, use that URL instead.)

2. Create an index

An index is where your content lives once Datalumo has read and embedded it. You'll usually keep one index per knowledge base.

Choose your embedding model now. It's fixed for the life of the index, so changing it later means re-indexing.

dl index create docs

In admin: Indexes → Add index.

3. Add your content

The fastest way is to upload files. Datalumo reads PDF, Word, Markdown, HTML, and plain text:

dl upload docs handbook.pdf faq.md

In admin: open the index and click Upload files.

Already have your content as data? Send items straight to the API. Each item needs a stable id and the searchable_text to embed:

curl -X POST http://localhost:3000/v1/indexes/docs/items \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [{
      "id": "refunds",
      "title": "Refund policy",
      "searchable_text": "You can request a refund within 30 days.",
      "metadata": { "url": "https://example.com/refunds" }
    }]
  }'

Send the same id again with unchanged text and it costs nothing, Datalumo skips it. Change the text and it re-embeds.

To keep an index in sync with an S3 bucket or a local folder, add a Source in admin (or dl sync add). For a one-off pull, see dl pull --help.

4. Create an app

An app is what your users actually talk to. It points at one or more indexes and holds the settings: how it retrieves, its persona, and how the widget looks.

dl app create support-bot --indexes docs --type chat

In admin: Apps → New app, pick Search or Chat, and choose your indexes.

You can also define an app in config:

{
  "name": "support-bot",
  "indexes": ["docs"],
  "persona": "You are a helpful assistant. Cite your sources.",
  "retrieval": { "k": 8, "minScore": 0.15, "hybrid": true },
  "widget": { "name": "Support", "greeting": "Hi! Ask me anything.", "summary": true }
}

5. Try it

dl app search support-bot "how do refunds work?"
dl app chat support-bot "How do refunds work?"

Or over HTTP:

curl -s http://localhost:3000/v1/apps/support-bot/search \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"how do refunds work?"}' | jq

Answers come back with citations that link to the source. Chat can stream over SSE. The full API is at /docs.

6. Put it on your site

1. Open your app in admin and go to Deploy.
2. Create a publishable key and restrict it to your domain.
3. Copy the one-line snippet onto your page.

That's it, your widget is live. See The widget for options like custom colors, a greeting, and programmatic control.

Running several sites

Serving more than one site from a single instance is the common case. For each site:

• Create one index and one app (site-a, site-b).
• Create one publishable key per site, locked to that site's domain.
• Push content on publish with POST /v1/indexes/{index}/items using stable IDs (like post:123).

Admin at a glance

Next steps

• Adding content: upload, sync a source, or push from your app.
• The widget: put search and chat on your site.
• Keys and access: admin keys, publishable keys, spend caps.
• The full API reference lives at /docs on your running instance.