Authentication

The Lexcel public API authenticates with API keys. Each key belongs to one organization and carries a set of scopes that control which endpoints it can call. A key is either workspace-bound (limited to a single workspace) or org-scoped (can act on any workspace its creator can access).

Base URL

https://api.lexcel.ai/public

All resources are versioned under /v1. The interactive API Reference is generated from the live OpenAPI spec at https://api.lexcel.ai/public/openapi.json.

Creating an API key

API keys are created from within the Lexcel app. You need the Manage workspace privilege on the target workspace.

1. Open the workspace you want the key to access.
2. Go to Settings → API Keys.
3. Click Create key, give it a name, and select the scopes it needs.
4. Copy the key immediately — the full value is shown only once.

Keys look like:

lxcl_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Caution

Treat API keys like passwords. Never commit them or expose them in client-side code. If a key leaks, revoke it from Settings → API Keys and create a new one.

Making authenticated requests

Send the key as a Bearer token in the Authorization header:

curl https://api.lexcel.ai/public/v1/org \
  -H "Authorization: Bearer lxcl_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Discovering your workspaces

Resolve which org and workspace(s) the key can reach before calling workspace-scoped endpoints:

1. GET /v1/org — confirms which organization the key belongs to.
2. GET /v1/workspaces — lists the workspace(s) the key can access (one for a workspace-bound key, potentially several for an org-scoped key); note the workspaceId.
3. Use that id in the path of every workspace-scoped call, e.g. POST /v1/workspaces/{workspace_id}/query.

Requesting a workspace the key cannot access returns 403.

Scopes

Each key carries one or more scopes. Grant only what an integration needs.

Scope	Grants access to
workspaces:read	GET /v1/org, /v1/workspaces, /v1/workspaces/{id}, .../projects
documents:read	GET /v1/workspaces/{id}/documents (document tree)
documents:write	POST /v1/workspaces/{id}/documents (upload)
query:run	POST /v1/workspaces/{id}/query (agent query)

A request to an endpoint whose required scope the key lacks returns 403 Forbidden with a detail explaining which scope is missing.

Rate limits

Requests are rate limited per API key (default 100 requests/minute). When exceeded, the API returns 429 Too Many Requests with a Retry-After header (seconds until the window resets).

Error responses

Status	Meaning
401	Missing or invalid API key
403	Key revoked/expired, missing scope, or wrong workspace
429	Rate limit exceeded — retry after the Retry-After interval
503	Temporarily unavailable (e.g. capacity) — retry after Retry-After

Error bodies are JSON: { "detail": "..." }.