Quickstart

From zero to a queryable workspace in five requests.

Quickstart

From zero to a queryable workspace in five requests.

This walkthrough takes you from a fresh API key to a workspace that can answer questions over an uploaded document.

Prerequisites

An API key issued by a LumenOne superadmin (see Authentication)
The X-Account-Id UUID for the account you’ll work with
A file to upload (PDF, TXT, DOCX, etc.)

We’ll use these shell variables throughout:

$ export LUMENONE_HOST="https://your-lumenone-host"
$ export API_KEY="your-api-key"
$ export ACCOUNT_ID="11111111-2222-3333-4444-555555555555"

1. Verify your credentials

$ curl "$LUMENONE_HOST/api/v1/auth" \
>   -H "Authorization: Bearer $API_KEY"

Expected:

1 { "authenticated": true }

2. Find your organization

$ curl "$LUMENONE_HOST/api/v1/orgs" \
>   -H "Authorization: Bearer $API_KEY" \
>   -H "X-Account-Id: $ACCOUNT_ID"

Pick an org from the response. Save both slugs — you’ll need each in different places:

$ export ORG_SLUG_HEX="61636d65"        # response.slug          → URL paths
$ export ORG_SLUG="acme"                # response.originalSlug  → bodies, docpaths

3. Upload a document

$ curl -X POST "$LUMENONE_HOST/api/v1/org/$ORG_SLUG_HEX/document/upload" \
>   -H "Authorization: Bearer $API_KEY" \
>   -H "X-Account-Id: $ACCOUNT_ID" \
>   -F "file=@./handbook.pdf"

The response includes the document’s location — that’s its docpath:

1 {
2   "success": true,
3   "documents": [
4     {
5       "location": "acme/custom-documents/handbook.pdf-6e8be64c-...json"
6     }
7   ]
8 }

$ export DOCPATH="acme/custom-documents/handbook.pdf-6e8be64c-...json"

4. Embed the document into a workspace

Find a workspace under your org and grab its hex slug:

$ curl "$LUMENONE_HOST/api/v1/org/$ORG_SLUG_HEX/workspaces" \
>   -H "Authorization: Bearer $API_KEY" \
>   -H "X-Account-Id: $ACCOUNT_ID"

$ export WORKSPACE_SLUG_HEX="6d792d776f726b7370616365"

Add the document:

$ curl -X POST "$LUMENONE_HOST/api/v1/workspace/$WORKSPACE_SLUG_HEX/update-embeddings" \
>   -H "Authorization: Bearer $API_KEY" \
>   -H "X-Account-Id: $ACCOUNT_ID" \
>   -H "Content-Type: application/json" \
>   -d "{\"adds\": [\"$DOCPATH\"]}"

5. (Shortcut) Upload + embed in one call

You can skip step 4 by passing addToWorkspaces at upload time. Note: this field uses the original workspace slug, not the hex form.

$ curl -X POST "$LUMENONE_HOST/api/v1/org/$ORG_SLUG_HEX/document/upload" \
>   -H "Authorization: Bearer $API_KEY" \
>   -H "X-Account-Id: $ACCOUNT_ID" \
>   -F "file=@./handbook.pdf" \
>   -F "addToWorkspaces=my-workspace,sales-workspace"

What’s next

Browse the full API Reference
Learn the slug encoding rules — the most common source of errors
See Errors for diagnosing failed requests