Get started

General concepts

The partner/account/org/workspace hierarchy, opaque ids, folders, and embedding.

The hierarchy

Your company  (your API key — internally called a "Partner")
├── Prompt templates  (id → templateId; versioned, assignable to any workspace)
└── Account  (id → X-Account-Id header)
    └── Organization  (id → orgId in URL)
        ├── Workspaces  (id → workspaceId in URL)
        │   └── Integrations  (voice, WhatsApp, Telegram)
        ├── Documents   (id → documentId; organized in folders)
        └── Tools       (id → toolId)

Every API call carries enough context to resolve a path through this tree:

LayerHow it’s identified
Your companyAPI key (Bearer token)
Accountid → X-Account-Id header
Organizationid → {orgId} in the URL path
Workspaceid → {workspaceId} in the URL path
Documentid → {documentId} in the URL path
Toolid → {toolId} in the URL path
Prompt templateid → {templateId} in the URL path; its versions → {versionId}

Identifiers are opaque

Every resource returns an id — a UUID. That id is the only way the API addresses a resource.

Take the id a resource returns and pass it back as-is — in the URL path or the X-Account-Id header. Do not construct, parse, hex-encode, or otherwise transform ids. There is no separate “slug” form to worry about.

You obtain ids from the list and detail endpoints, for example:

  • Accounts — GET /v1/accounts
  • Organizations — GET /v1/organizations (scoped by X-Account-Id)
  • Workspaces — GET /v1/organizations/{orgId}/workspaces
  • Documents — GET /v1/organizations/{orgId}/documents
  • Prompt templates — GET /v1/prompt-templates (partner-level: no X-Account-Id)

Account scoping

Account-scoped routes require the X-Account-Id header, and the resource in the URL must belong to that account:

  • The account must be owned by your company (partner), or you get 403.
  • The org/workspace/document/tool must live under that account, or you get 404 — a valid id from a different account will not resolve.

This is by design: the same key can serve many accounts, and the header is what selects which one a request applies to.

Documents and folders

A document is a file uploaded into an organization’s storage. Documents are organized into folders within the org:

  • List folders with GET /v1/organizations/{orgId}/folders; create one with POST /v1/organizations/{orgId}/folders.
  • If you upload without naming a folder, the document lands in custom-documents, the catch-all for unfiled docs.
  • The target folder must already exist before you upload into it.

A document’s id is stable and shared: the same id identifies the org document and every workspace that has it embedded. You address the document by that one id everywhere.

Only single-document file types are accepted for upload: pdf, docx, pptx, odt, odp, txt, md, rst, adoc, org, html, csv, epub.

Workspaces and embedding

Uploading a document does not automatically make it queryable. To use a document in a workspace, embed it:

PUT /v1/workspaces/{workspaceId}/documents/{documentId}

Notes:

  • The document must belong to the same organization as the workspace.
  • Embedding is idempotent — re-embedding a document that is already embedded in the workspace is a no-op and returns success.
  • Remove an embedding with DELETE /v1/workspaces/{workspaceId}/documents/{documentId} (this detaches it from the workspace; the org document itself is unaffected).

Workspace integrations

Each workspace can connect to external channels, each managed under /v1/workspaces/{workspaceId}/integrations/...:

  • voice — a phone assistant (a LumenOne-owned routing number the customer forwards their line to)
  • whatsapp — WhatsApp Business
  • telegram — a Telegram bot

Reading a workspace (GET /v1/workspaces/{workspaceId}) inlines each channel’s status. A channel that is not set up reads { connected: false }, and secret tokens are never returned.

Go deeper

Each resource has its own guide under Core concepts: