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.
The Lucent Data API is a REST surface for reading Lucent data and updating
issue status from scripts, dashboards, and services.
Base URL
All endpoints below are relative to this base URL.
Authentication
Send a bearer token in the Authorization header:
curl -sS https://app.lucenthq.com/api/v1/issues?limit=10 \
-H "Authorization: Bearer luc_api_..."
- API keys that start with
luc_api_
- OAuth access tokens that start with
luc_oat_
Legacy static keys with the luc_mcp_ prefix continue to work.
Read endpoints require read:lucent. Updating issue status requires
write:issues.
Create API keys in Organization settings → MCP. Choose Allow issue status
updates when the key needs to call PATCH /api/v1/issues/{issueId}.
OAuth clients should follow the OAuth reference and request only
the scopes they need.
Browser dashboard sessions do not authenticate the Data API. These endpoints
are for bearer-token clients and return JSON errors when the token is missing
or invalid.
Endpoints
| Method | Path | Scope | Query params | Description |
|---|
GET | /api/v1/issues | read:lucent | limit, status, cursor | List issues for the token’s organization. |
GET | /api/v1/issues/{issueId} | read:lucent | — | Fetch a single issue by UUID. |
PATCH | /api/v1/issues/{issueId} | write:issues | — | Update an issue’s status. |
GET | /api/v1/signals | read:lucent | limit, cursor | List configured signals and match counts. |
GET | /api/v1/insights | read:lucent | limit, cursor | List recent AI-generated insights. |
orgId query parameter.
Limits
| Endpoint | Default limit | Max limit |
|---|
/api/v1/issues | 25 | 200 |
/api/v1/signals | 50 | 200 |
/api/v1/insights | 25 | 100 |
limit must be an integer within the endpoint’s range.
List endpoints are ordered by createdAt descending, then id descending.
List responses include nextCursor:
{
"issues": [],
"nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTAyLTI0VDEwOjMyOjE5LjA2NloiLCJpZCI6Ijg3YjNhNmI2LTVhZjUtNDM4Yi1hMzljLWVmZjE0OGE2OGNjYiJ9"
}
nextCursor is not null, pass it back as the cursor query parameter to
fetch the next page:
GET /api/v1/issues?limit=25&cursor=eyJjcmVhdGVkQXQiOiIyMDI2...
Authorization: Bearer luc_api_...
Rate limits
| Request type | Limit |
|---|
| Reads | 300 requests per minute per token or OAuth client |
| Writes | 60 requests per minute per token or OAuth client |
429 and include Retry-After,
X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.
Errors
All error responses are JSON and include Cache-Control: no-store.
| Status | Example body | Meaning |
|---|
400 | {"error":"limit must be an integer between 1 and 200"} | Invalid query parameter. |
400 | {"error":"Request body must be valid JSON"} | Invalid JSON body for a write request. |
400 | {"error":"status must be one of: unresolved, ticket_created, transient, resolved"} | Invalid issue status. |
401 | {"error":"Missing or invalid bearer token"} | Missing, malformed, revoked, or unknown bearer token. |
403 | {"error":"Missing required scope: write:issues"} | The token is valid but lacks the required scope. |
404 | {"error":"Issue not found"} | The requested issue was not found in the token’s organization. |
429 | {"error":"Rate limit exceeded"} | The token or OAuth client exceeded its per-minute limit. |
401 responses include:
WWW-Authenticate: Bearer scope="read:lucent"
write:issues.
