> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.lumenia.net/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.lumenia.net/_mcp/server.

# Quickstart

This walkthrough takes you from a fresh API key to a configured workspace assistant that answers questions using your knowledge base — and shows how end users reach it by phone or chat.

## Prerequisites

* An API key issued by a LumenOne superadmin ([see Authentication](/documentation/get-started/authentication))
* The `id` of the account (your customer) you'll work in — list them with `GET /v1/accounts`
* A file to upload (PDF, TXT, DOCX, etc. — see the [supported types](/documentation/core-concepts/documents))

We'll use these shell variables throughout:

```bash
export LUMENONE_HOST="https://app.lumenia.net"
export API_KEY="your-api-key"
export ACCOUNT_ID="550e8400-e29b-41d4-a716-446655440000"
```

## 1. Verify your credentials

```bash
curl "$LUMENONE_HOST/api/v1/me" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Account-Id: $ACCOUNT_ID"
```

Expected — the partner, plus the account when the header is valid:

```json
{
  "partner": { "name": "Acme Partner", "createdAt": "2026-06-15T05:24:00.000Z" },
  "account": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "LumenIA", "type": "ipaas", "createdAt": "2026-06-15T05:24:00.000Z" }
}
```

## 2. Create an organization

Organizations are the tenants under an account. Create one (or reuse an existing id from `GET /v1/organizations`):

```bash
curl -X POST "$LUMENONE_HOST/api/v1/organizations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Account-Id: $ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Support Org" }'
```

Save the returned `id`:

```bash
export ORG_ID="7c3e1b90-2a4d-4f6b-9e21-1f0c2d3a4b5c"
```

## 3. Create a workspace

A workspace is the actual assistant. Create one under the org:

```bash
curl -X POST "$LUMENONE_HOST/api/v1/organizations/$ORG_ID/workspaces" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Account-Id: $ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Support" }'
```

```bash
export WORKSPACE_ID="9b8a7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"
```

## 4. Set the assistant's prompt

The workspace's **base system prompt** (`chat.prompt`) shapes how it answers. Update it with a partial `PATCH` — only the fields you send change:

```bash
curl -X PATCH "$LUMENONE_HOST/api/v1/workspaces/$WORKSPACE_ID" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Account-Id: $ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{ "chat": { "prompt": "You are the Acme support assistant. Answer only from the provided context; if it is not there, say you do not know." } }'
```

> **Info**
>
> `chat.prompt` drives text answers **and** answers synthesized from the knowledge base (including a voice assistant's knowledge-base replies). The **live voice conversation** has its own separate prompt, set on the voice integration in step 7. See [Workspaces](/documentation/core-concepts/workspaces).

This sets the prompt manually, on this one workspace. If you run **many workspaces on the same playbook**, define the prompt once as a versioned [prompt template](/documentation/core-concepts/prompt-templates) and pin it to each workspace instead — a pinned template overrides the manual prompt.

## 5. Add knowledge: upload a document

Upload a file into the organization (omit `folder` to use the default `custom-documents`):

```bash
curl -X POST "$LUMENONE_HOST/api/v1/organizations/$ORG_ID/documents" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Account-Id: $ACCOUNT_ID" \
  -F "file=@./handbook.pdf"
```

Save the returned document `id`:

```bash
export DOCUMENT_ID="b927e9d2-ad7c-442b-9280-32b56d105629"
```

## 6. Embed the document into the workspace

Uploading does not make a document queryable — embed it into the workspace by id:

```bash
curl -X PUT "$LUMENONE_HOST/api/v1/workspaces/$WORKSPACE_ID/documents/$DOCUMENT_ID" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Account-Id: $ACCOUNT_ID"
```

The document and workspace must belong to the same organization. Embedding is idempotent. See [Documents & knowledge base](/documentation/core-concepts/documents).

## 7. Connect a channel so people can talk to it

The workspace is now configured, but there is **no direct chat endpoint** — end users reach the assistant through a channel you connect. Pick one (or several):

### By phone — voice integration

Add a voice integration; a routing number is auto-assigned from the pool:

```bash
curl -X POST "$LUMENONE_HOST/api/v1/workspaces/$WORKSPACE_ID/integrations/voice" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Account-Id: $ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{ "firstMessage": "Hi, thanks for calling Acme support. How can I help?", "prompt": "You are a warm, concise phone assistant for Acme support." }'
```

Give the customer the returned `phoneNumber` and have them **forward their business line** to it. Callers then dial the customer's normal number and talk to the assistant. Field values (voice, transcriber) come from `GET /v1/integrations/voice/options`. See [Voice integration & routing numbers](/documentation/core-concepts/voice-integration).

### By chat — WhatsApp or Telegram

Connect a messaging channel and the workspace answers messages sent to it:

* **Telegram** — connect a bot token from BotFather with `PUT /v1/workspaces/$WORKSPACE_ID/integrations/telegram`; users then message the bot. See [Telegram integration](/documentation/core-concepts/telegram-integration).
* **WhatsApp** — run the Embedded Signup flow (mint a connect token, then complete onboarding — including picking the phone number — in the iframe); users then message that WhatsApp number. See [WhatsApp integration](/documentation/core-concepts/whatsapp-integration).

> **Info**
>
> Interaction is immediate once a channel is connected: call the (forwarded) phone number, message the WhatsApp number, or open the Telegram bot. The same configured workspace — its prompt, knowledge, and tools — powers every channel.

## What's next

* Give the assistant actions to take mid-conversation with [Tools](/documentation/core-concepts/tools)
* Roll out one prompt to many workspaces — and version it — with [Prompt templates](/documentation/core-concepts/prompt-templates)
* Browse the full [API Reference](/api-reference)
* See [Errors](/documentation/get-started/errors) for diagnosing failed requests