Introduction

Welcome to Lumen — the embeddable AI assistant that reads your website, learns from your documents, and answers customer questions instantly.

Lumen combines four things in one platform:

Web crawler — indexes your site, even JavaScript-rendered SPAs
File ingestion — extracts text from PDFs, CSVs, JSON, and more
Vector search — semantic retrieval via Qdrant (15ms p99)
Agentic AI — Gemini 2.5 Flash with tool calling

New here? Start with the Quick start guide — you can have Lumen running on your site in under 10 minutes.

Quick start

Get Lumen live on your website in four steps.

1. Create your account

2. Create a workspace

A workspace is your isolated AI tenant. Each workspace has its own knowledge base, chat history, and API keys.

3. Add knowledge

Connect your data sources from the dashboard:

Crawl your site — paste your homepage URL, choose page count
Upload files — drag PDFs, CSVs, or other documents

4. Embed the widget

Copy this code into your site's <body>:

<div id="lumen-widget" data-tenant="your-workspace-id"></div>
<script type="module" src="https://cdn.lumen.ai/widget.es.js"></script>

That's it. Your AI assistant is live.

Core concepts

Workspaces

A workspace is a fully-isolated tenant. Each workspace has:

Its own vector storage (Qdrant collection)
Separate API keys
Independent chat history and analytics

Agentic RAG

Lumen doesn't just match keywords. The AI agent decides which retrieval tool to use:

search_knowledge_base — finds specific text chunks
get_page_overviews — searches AI-generated page summaries

The agent can chain up to 4 tool calls before answering. This means accurate answers with sources, not hallucinations.

Live context

Push real-time data from your page into the AI's context — current user, cart contents, page state. The bot answers using what's currently on screen, no server-side polling needed.

Embed code

The simplest embed:

<div id="lumen-widget" data-tenant="your-workspace-id"></div>
<script type="module" src="https://cdn.lumen.ai/widget.es.js"></script>

With full configuration:

<div id="lumen-widget"
     data-tenant="your-workspace-id"
     data-config='{"botName":"Aria","color":"#0891b2","theme":"auto"}'
     data-context='{"page":"pricing","plan":"pro"}'>
</div>
<script type="module" src="https://cdn.lumen.ai/widget.es.js"></script>

Configuration

Configure the widget via data-config JSON:

Option	Type	Default	Description
`botName`	string	`"Lumen"`	Display name of the bot
`tagline`	string	`"AI assistant"`	Tagline shown under bot name
`color`	hex	`"#0891b2"`	Primary brand color
`theme`	string	`"auto"`	`"light"`, `"dark"`, or `"auto"`
`suggestions`	string[]	3 defaults	Quick-start question buttons
`streaming`	boolean	`true`	Use SSE streaming responses
`startOpen`	boolean	`false`	Open widget on page load

Theming

The widget auto-detects your site's theme by watching for .dark class on <html> or <body>. You can also force a theme:

data-config='{"theme":"dark"}'

JavaScript API

Control the widget programmatically via window.Lumen:

`Lumen.ask(question)`

Open the widget and send a question:

document.getElementById('help-btn').addEventListener('click', () => {
    Lumen.ask('How do I reset my password?');
});

`Lumen.updateContext(data)`

Push live data into the AI's context:

Lumen.updateContext({
    user: { name: "Sarah", plan: "Pro" },
    cart: { items: 3, total: "$142" }
});

Live context

Live context is what makes Lumen powerful for dynamic sites. The bot answers using whatever data is currently on the page.

Stocks / dashboard example

setInterval(() => {
    Lumen.updateContext({
        prices: { AAPL: 189.45, TSLA: 248.12 },
        marketStatus: "OPEN"
    });
}, 5000);

Now ask the bot: "What's Apple trading at?" — it answers from the page's data.

Web crawling

Lumen's crawler handles modern websites including JavaScript-rendered SPAs.

Starting a crawl

From the dashboard, navigate to Web Crawling, paste your URL, choose page count (5–100), and click Start. The crawler:

Reads robots.txt and respects directives
Fetches sitemap.xml if available
Falls back to crawling links from your homepage
For each page: extracts text, summarizes, chunks, embeds, stores in Qdrant

Re-crawling

Crawl the same URL again to refresh content. Lumen deduplicates by content hash — only changed pages are re-indexed.

File ingestion

Upload documents from the Files page in your dashboard. Drag-and-drop or click to browse.

Supported formats

Format	Extensions	Max size
PDF	`.pdf`	20 MB
Word	`.docx`	20 MB
CSV	`.csv`	20 MB
JSON	`.json`	20 MB
HTML	`.html`, `.htm`	20 MB
Markdown	`.md`	20 MB
Text	`.txt`	20 MB

Authentication

API requests use one of two methods:

Admin token (JWT) — for dashboard operations
API key (workspace-scoped) — for widget and chat API

API key header

x-api-key: lumen_pk_a1b2c3d4...

Chat API

Send messages and receive AI responses.

POST /api/chat

POST /api/chat
Headers: { "x-api-key": "lumen_pk_..." }
Body: {
  "message": "What is your refund policy?",
  "context": { "page": "pricing" }
}

Response:
{
  "answer": "We offer a 30-day money-back guarantee...",
  "sources": [{ "url": "/refund-policy", "title": "Refund Policy" }],
  "tools_used": ["search_knowledge_base"]
}

POST /api/chat/stream

Same as /chat but streams tokens via Server-Sent Events.

Crawl API

POST /api/crawl

POST /api/crawl
Body: {
  "url": "https://example.com",
  "maxPages": 50,
  "usePuppeteer": true
}

Response: { "jobId": "abc-123" }

GET /api/crawl/jobs/:jobId

Poll job status: pending → running → done | failed

Files API

POST /api/files/upload

Upload a file via multipart/form-data.

GET /api/files

List uploaded files for the workspace.

DELETE /api/files/:id

Delete a file and remove its vectors.

Rate limits

Per-IP rate limits across the platform:

Endpoint	Limit
POST /api/chat	30 / minute
POST /api/crawl	5 / 10 minutes
POST /api/files/upload	10 / minute
All endpoints	300 / 15 minutes

Plan limits are checked monthly per workspace and are separate from per-IP rate limits. See pricing for plan details.

Error codes

Code	Meaning
`400`	Bad request — missing or invalid parameters
`401`	Invalid or missing API key
`403`	Forbidden — insufficient permissions
`404`	Resource not found
`409`	Conflict — duplicate file or workspace
`422`	Unprocessable — content extraction failed
`429`	Rate limit exceeded
`500`	Server error
`503`	AI service unavailable

Need help? Email support@lumen.ai or visit our homepage.