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)
• 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)

We’ll use these shell variables throughout:

$
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

$
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:

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

2. Create an organization

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

$
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:

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

3. Create a workspace

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

$
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" }'

$
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:

$
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." } }'

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 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):

$
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:

$
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:

$
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.

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:

$
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.

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.
• 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.

What’s next

• Give the assistant actions to take mid-conversation with Tools
• Roll out one prompt to many workspaces — and version it — with Prompt templates
• Browse the full API Reference
• See Errors for diagnosing failed requests