Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.lucenthq.com/llms.txt

Use this file to discover all available pages before exploring further.

Lucent uses different credentials for write-only ingest and bearer-token Data API access.
APICredentialWhere to use it
Ingest APIluc_pk_... public keyX-Lucent-Api-Key header or api_key query parameter
Data APIluc_api_... API key or luc_oat_... OAuth access tokenAuthorization: Bearer ... header

​
Ingest public keys

All requests to the Lucent ingest API are authenticated with a public key issued from your dashboard. Public keys begin with luc_pk_ and are scoped to a single organization. They are write-only — they can submit session data but cannot read anything back, which is why it is safe to embed them in client-side JavaScript.

​
Key format

luc_pk_7a4f9e2b6c1d3f...
Create and revoke keys at Settings → SDK keys in app.lucenthq.com.

​
Passing the key

Lucent accepts the key in either an HTTP header or a query parameter. The header is preferred; the query parameter exists so that navigator.sendBeacon requests (which cannot set custom headers) can still authenticate on page unload. 
POST /api/sdk/replay HTTP/1.1
Host: batch-jobs-lucent.onrender.com
Content-Type: application/json
X-Lucent-Api-Key: luc_pk_...

​
Ingest error responses

​
401 Unauthorized
  • {"error": "Missing API key"} — no X-Lucent-Api-Key header or api_key query parameter was supplied.
  • {"error": "Invalid or revoked API key"} — the key is not recognized or has been revoked in the dashboard.
​
429 Too Many Requests
Rate limit exceeded. The response includes a Retry-After header with the number of seconds until the limit resets.

​
Ingest rate limits

Each API key is limited to 100 requests per minute per key, using a sliding‑window algorithm. With the SDK’s default batching settings (flushIntervalMs: 10_000), a single browser session produces roughly 6 requests per minute — well under the limit. If you build a custom server‑side integration that aggregates many sessions through a single key, you may need multiple keys or a higher tier. Contact [email protected] if you run into limits.

​
CORS

The ingest API responds with Access-Control-Allow-Origin: *, so you can call it from any browser origin. The following headers are allowed on requests:
  • Content-Type
  • Content-Encoding (for gzipped bodies)
  • X-Lucent-Api-Key
Preflight OPTIONS requests are handled automatically and require no special client configuration.

​
Data API bearer tokens

The Data API uses API keys and OAuth bearer tokens for reading data and updating issue status. 
GET /api/v1/issues HTTP/1.1
Host: app.lucenthq.com
Authorization: Bearer luc_api_...
Supported token types:
  • luc_api_... — an API key created in Organization settings → MCP
  • luc_oat_... — an OAuth access token
Legacy static keys with the luc_mcp_ prefix continue to work. Bearer tokens are scoped to the organization that created or authorized them. You cannot override the organization with a request parameter.

​
Data API scopes

ScopeAllows
read:lucentRead issues, signals, and insights.
write:issuesUpdate issue status.
API keys default to read:lucent. When creating an API key, enable Allow issue status updates to add write:issues. OAuth clients must request the scopes they need; unknown scopes are rejected.

​
Data API error responses

​
401 Unauthorized
{"error": "Missing or invalid bearer token"} — no bearer token was supplied, the token prefix is not supported, the token was revoked, or the token is unknown.
​
403 Forbidden
{"error": "Missing required scope: write:issues"} — the bearer token is valid but does not include the scope required by the endpoint.
401 responses include this challenge header: 
WWW-Authenticate: Bearer scope="read:lucent"
For write endpoints, the challenge uses scope="write:issues".